# Request verification code
Source: https://docs.openwhispr.com/api-reference/auth/request-verification-code
/openapi.json post /auth/email-code
Send a 6-digit verification code to the given email address. The code expires after 10 minutes.
# Verify code
Source: https://docs.openwhispr.com/api-reference/auth/verify-code
/openapi.json post /auth/email-code/verify
Verify a 6-digit code and receive a short-lived session token (valid for 15 minutes).
# Create folder
Source: https://docs.openwhispr.com/api-reference/folders/create-folder
/openapi.json post /folders/create
Create a new folder. Max 50 folders per user.
# List folders
Source: https://docs.openwhispr.com/api-reference/folders/list-folders
/openapi.json get /folders/list
List all folders sorted by sort_order, then created_at.
# Create API key
Source: https://docs.openwhispr.com/api-reference/keys/create-api-key
/openapi.json post /keys/create
Create a new API key. The full key is only returned once in the response.
# List API keys
Source: https://docs.openwhispr.com/api-reference/keys/list-api-keys
/openapi.json get /keys/list
List all active API keys for the authenticated user.
# Revoke API key
Source: https://docs.openwhispr.com/api-reference/keys/revoke-api-key
/openapi.json post /keys/{id}/revoke
Revoke an API key. The key will stop working immediately.
# Create note
Source: https://docs.openwhispr.com/api-reference/notes/create-note
/openapi.json post /notes/create
Create a new note.
# Delete note
Source: https://docs.openwhispr.com/api-reference/notes/delete-note
/openapi.json delete /notes/{id}
Soft-delete a note.
# Get note
Source: https://docs.openwhispr.com/api-reference/notes/get-note
/openapi.json get /notes/{id}
Get a single note by ID.
# List notes
Source: https://docs.openwhispr.com/api-reference/notes/list-notes
/openapi.json get /notes/list
List notes with optional folder filtering and cursor pagination.
# Search notes
Source: https://docs.openwhispr.com/api-reference/notes/search-notes
/openapi.json post /notes/search
Search notes using hybrid semantic (vector) and full-text search. Costs 5x against the rate limit.
# Update note
Source: https://docs.openwhispr.com/api-reference/notes/update-note
/openapi.json patch /notes/{id}
Update a note's title, content, or folder. All fields are optional — only provided fields are updated.
# List spaces
Source: https://docs.openwhispr.com/api-reference/spaces/list-spaces
/openapi.json get /spaces/list
List the team spaces a workspace API key can address, sorted by name. Archived spaces are omitted. Requires a workspace key (ow_wks_live_) holding any of workspace:notes:read, workspace:notes:write, workspace:folders:read or workspace:folders:write.
# Delete transcription
Source: https://docs.openwhispr.com/api-reference/transcriptions/delete-transcription
/openapi.json delete /transcriptions/{id}
Soft-delete a transcription by ID.
# Get note transcript
Source: https://docs.openwhispr.com/api-reference/transcriptions/get-note-transcript
/openapi.json get /notes/{id}/transcript
Get the transcript associated with a note. If the note has a linked transcription record, returns it with structured segments. For older notes with only raw transcript text, returns the text with segments as null.
# Get transcription
Source: https://docs.openwhispr.com/api-reference/transcriptions/get-transcription
/openapi.json get /transcriptions/{id}
Get a single transcription by ID. Supports multiple output formats including SRT and VTT subtitles.
# List transcriptions
Source: https://docs.openwhispr.com/api-reference/transcriptions/list-transcriptions
/openapi.json get /transcriptions/list
List transcription history with cursor pagination, newest first. Supports filtering by language or linked note.
# Get usage
Source: https://docs.openwhispr.com/api-reference/usage/get-usage
/openapi.json get /usage
Get current usage statistics, word counts, and plan details.
# Errors
Source: https://docs.openwhispr.com/api/errors
Error codes and how to handle them.
All errors follow the same format:
```json theme={null}
{
"error": {
"code": "not_found",
"message": "Note not found"
}
}
```
## Error codes
| HTTP status | Code | Description |
| ----------- | -------------------- | -------------------------------------------------------------------------------------------------- |
| 400 | `validation_error` | Invalid request body or query parameters. Check the `message` for details. |
| 400 | `limit_reached` | You've hit a cap on the resource — for example, the maximum number of active API keys. |
| 401 | `invalid_api_key` | Missing, malformed, expired, or revoked API key. |
| 401 | `invalid_code` | The email verification code is wrong or has expired. See [Agent setup](/integrations/agent-setup). |
| 403 | `forbidden` | Your API key doesn't have the required scope for this endpoint. |
| 404 | `not_found` | The resource doesn't exist or belongs to another user. |
| 404 | `no_transcript` | The note exists but has no transcript attached. |
| 405 | `method_not_allowed` | Wrong HTTP method. Check the endpoint documentation. |
| 409 | `conflict` | Duplicate resource — for example, a folder with the same name already exists. |
| 429 | `rate_limited` | Rate limit exceeded. Check the `Retry-After` header. |
| 429 | `too_many_attempts` | Too many failed verification-code attempts. Request a new code. |
| 500 | `internal_error` | Something went wrong on our end. Retry after a short delay. |
## Handling errors
```javascript theme={null}
const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
if (!res.ok) {
const { error } = await res.json();
if (error.code === "rate_limited") {
const retryAfter = res.headers.get("Retry-After");
await new Promise((r) => setTimeout(r, retryAfter * 1000));
// retry the request
}
throw new Error(`${error.code}: ${error.message}`);
}
```
```python theme={null}
import time, requests
res = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
if res.status_code == 429:
retry_after = int(res.headers.get("Retry-After", 5))
time.sleep(retry_after)
# retry the request
res.raise_for_status()
```
# API overview
Source: https://docs.openwhispr.com/api/overview
Authenticate, understand rate limits, and work with the OpenWhispr REST API.
The OpenWhispr API lets you manage notes, folders, transcriptions, and usage programmatically. All endpoints live under `/api/v1`. Most require an API key — the exceptions are covered below.
## Base URL
```
https://api.openwhispr.com/api/v1
```
## Authentication
Most requests need a Bearer token in the `Authorization` header.
```bash theme={null}
curl -H "Authorization: Bearer owk_live_YOUR_KEY" \
https://api.openwhispr.com/api/v1/notes/list
```
Generate API keys from the OpenWhispr desktop app: open **Integrations** in the left sidebar and use the **API** card. Keys start with `owk_live_` and are shown once at creation.
API key management is offered on paid plans.
Two exceptions: the [agent bootstrap](/integrations/agent-setup) endpoints
(`/auth/email-code`, `/auth/email-code/verify`) take no credentials at all —
that's how an assistant gets its first token. And the `/keys/*` management
endpoints also accept the short-lived session token (`owt_`) that bootstrap
produces, not just an `owk_live_` API key. Every other endpoint needs a
Bearer `owk_live_` (or `ow_wks_live_`) key.
### Scopes
Each key has scoped permissions. Requests missing the required scope get a `403 Forbidden` response.
| Scope | Access |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `notes:read` | List, get, and search notes. Read note transcripts. List folders. |
| `notes:write` | Create, update, and delete notes. Create folders. |
| `transcriptions:read` | List and get transcription history. |
| `transcriptions:delete` | Delete a transcription and its audio. Not offered in the desktop app — [create the key via the API](/integrations/agent-setup). |
| `usage:read` | Read usage statistics. Granted to every key automatically. |
Keys that start with `ow_wks_live_` are workspace keys and carry a different set of scopes — see [Workspace API keys](/api/workspace-keys).
## Response format
All responses use a consistent envelope.
```json Single resource theme={null}
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Meeting notes",
"content": "Discussed the roadmap..."
}
}
```
```json Paginated list theme={null}
{
"data": [
{ "id": "...", "title": "Note 1" },
{ "id": "...", "title": "Note 2" }
],
"has_more": true,
"next_cursor": "$NEXT_CURSOR"
}
```
```json Error theme={null}
{
"error": {
"code": "not_found",
"message": "Note not found"
}
}
```
## Pagination
List endpoints use cursor-based pagination. Treat `next_cursor` as an opaque
token — pass it back exactly as received via the `cursor` query parameter;
never parse or construct one yourself.
```bash theme={null}
# First page
curl -H "Authorization: Bearer $KEY" \
"https://api.openwhispr.com/api/v1/notes/list?limit=50"
# Next page — $NEXT_CURSOR is the next_cursor value from the previous response
curl -H "Authorization: Bearer $KEY" \
"https://api.openwhispr.com/api/v1/notes/list?limit=50&cursor=$NEXT_CURSOR"
```
When `has_more` is `false`, you've reached the end.
## Rate limits
Limits are per API key with minute and daily windows. A search request counts as 5 against both windows.
| Plan | Per minute | Per day |
| -------- | ---------- | ------- |
| Pro | 120 | 10,000 |
| Business | 300 | 50,000 |
Every response includes rate limit headers:
| Header | Description |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit` | Max requests per minute |
| `X-RateLimit-Remaining` | Remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when window resets |
| `Retry-After` | Seconds to wait (only on `429`) |
# API quickstart
Source: https://docs.openwhispr.com/api/quickstart
Make your first API call in under a minute.
Open the OpenWhispr desktop app, click **Integrations** in the left sidebar, then **Manage keys** on the **API** card and **Create API Key**.
Your key looks like `owk_live_abc123...` — copy it now, it's only shown once.
```bash curl theme={null}
curl -H "Authorization: Bearer owk_live_YOUR_KEY" \
https://api.openwhispr.com/api/v1/notes/list?limit=5
```
```javascript Node.js theme={null}
const res = await fetch("https://api.openwhispr.com/api/v1/notes/list?limit=5", {
headers: { Authorization: "Bearer owk_live_YOUR_KEY" },
});
const { data } = await res.json();
console.log(data);
```
```python Python theme={null}
import requests
res = requests.get(
"https://api.openwhispr.com/api/v1/notes/list",
params={"limit": 5},
headers={"Authorization": "Bearer owk_live_YOUR_KEY"},
)
print(res.json()["data"])
```
```bash curl theme={null}
curl -X POST \
-H "Authorization: Bearer owk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "My first API note", "title": "Hello from the API"}' \
https://api.openwhispr.com/api/v1/notes/create
```
```javascript Node.js theme={null}
const res = await fetch("https://api.openwhispr.com/api/v1/notes/create", {
method: "POST",
headers: {
Authorization: "Bearer owk_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
content: "My first API note",
title: "Hello from the API",
}),
});
const { data } = await res.json();
console.log(data.id);
```
```python Python theme={null}
import requests
res = requests.post(
"https://api.openwhispr.com/api/v1/notes/create",
headers={"Authorization": "Bearer owk_live_YOUR_KEY"},
json={"content": "My first API note", "title": "Hello from the API"},
)
print(res.json()["data"]["id"])
```
```bash curl theme={null}
curl -X POST \
-H "Authorization: Bearer owk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "meeting notes"}' \
https://api.openwhispr.com/api/v1/notes/search
```
```javascript Node.js theme={null}
const res = await fetch("https://api.openwhispr.com/api/v1/notes/search", {
method: "POST",
headers: {
Authorization: "Bearer owk_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "meeting notes" }),
});
const { data } = await res.json();
console.log(`Found ${data.length} results`);
```
```python Python theme={null}
import requests
res = requests.post(
"https://api.openwhispr.com/api/v1/notes/search",
headers={"Authorization": "Bearer owk_live_YOUR_KEY"},
json={"query": "meeting notes"},
)
print(f"Found {len(res.json()['data'])} results")
```
## Next steps
* [List notes](/api-reference/notes/list-notes) — full CRUD reference
* [Create folder](/api-reference/folders/create-folder) — organize notes into folders
* [MCP server](/integrations/mcp) — connect your AI assistant
# Workspace API keys
Source: https://docs.openwhispr.com/api/workspace-keys
Reach your team's shared notes and folders from the API using a workspace key.
A personal API key reaches your own notes. A **workspace key** reaches the notes and folders inside your team spaces, so an integration can read or write shared content without being tied to one person's account.
Workspace keys start with `ow_wks_live_` instead of `owk_live_`.
## Create a workspace key
Only a workspace **owner** or **admin** can create one.
In the desktop app, go to **Settings > Account > Workspace** and pick the **Developer** tab.
If you don't see the tab, your role in the workspace is member — ask an owner or admin.
Click **New key**, give it a name, and tick the permissions it needs.
The key is shown once. Copy it before closing the dialog — you can't see it again, only revoke it and make a new one.
A workspace can have up to **20** active keys at a time.
## Scopes
Workspace scopes are separate from personal ones, and they only ever apply to team-space content.
| Scope | Access |
| ------------------------- | -------------------------------------------------------------- |
| `workspace:notes:read` | List, get, and search notes in a space. Read note transcripts. |
| `workspace:notes:write` | Create, update, and delete notes in a space. |
| `workspace:folders:read` | List folders in a space. |
| `workspace:folders:write` | Create folders in a space. |
| `workspace:*` | Everything above. |
Any one of the four `notes`/`folders` scopes also lets the key list the spaces it can see.
The key-creation dialog offers a few more permissions than the ones listed here. Those cover areas the API doesn't expose yet, so a key holding only those can't call anything — stick to the scopes above.
## Naming a space
Endpoints that work across a collection need to know which space you mean. Pass the space's id as `space_id` — a query parameter on the list endpoints, a body field on the create ones:
| Endpoint | `space_id` |
| -------------------------------------- | ------------------------------------ |
| `GET /notes/list` | Required |
| `POST /notes/search` | Required |
| `POST /notes/create` | Required |
| `GET /folders/list` | Required |
| `POST /folders/create` | Required |
| `GET /notes/{id}` · `PATCH` · `DELETE` | Not used — the note id identifies it |
| `GET /notes/{id}/transcript` | Not used |
| `GET /spaces/list` | Not used |
Two rules the API enforces on the endpoints that take it:
* A **workspace key without** `space_id` gets `400 validation_error` — "space\_id is required for workspace API keys".
* A **personal key with** `space_id` gets the same status. A personal key can't reach team-space content, and silently ignoring the parameter would hide that.
## List the spaces a key can see
```bash theme={null}
curl -H "Authorization: Bearer ow_wks_live_YOUR_KEY" \
https://api.openwhispr.com/api/v1/spaces/list
```
```json theme={null}
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Engineering",
"slug": "engineering",
"description": "Team notes",
"emoji": "🛠",
"created_at": "2026-07-14T09:12:00.000Z",
"updated_at": "2026-07-28T16:04:00.000Z"
}
]
}
```
Archived spaces are left out. Take an `id` from here and pass it as `space_id`.
## Read notes from a space
```bash theme={null}
curl -H "Authorization: Bearer ow_wks_live_YOUR_KEY" \
"https://api.openwhispr.com/api/v1/notes/list?space_id=550e8400-e29b-41d4-a716-446655440000&limit=20"
```
Responses, pagination, and errors work exactly as they do for personal keys — see the [API overview](/api/overview).
## What workspace keys don't do
* **The CLI doesn't use them.** It works against your own notes — use a personal key.
* **The MCP server doesn't use them** either, for the same reason.
* **They can't reach private notes**, including your own. A workspace key sees team-space content and nothing else.
## Security
* Only the SHA-256 hash is stored, so a lost key can't be recovered — revoke it and create another.
* Naming a space that isn't in the key's workspace returns `404 not_found` rather than a permission error, so a key can't be used to discover which spaces exist elsewhere.
* Revoking a key stops it working immediately, and any integration using it starts failing at once.
# CLI authentication
Source: https://docs.openwhispr.com/cli/authentication
How the CLI authenticates to the local desktop app and the cloud API.
The CLI uses different credentials for each backend. Local needs nothing from you; remote needs an API key.
## Local backend (desktop bridge)
When the OpenWhispr desktop app is running, it exposes a loopback HTTP bridge on `127.0.0.1`. The app writes a one-time bearer token to `~/.openwhispr/cli-bridge.json` (mode `0600`) at startup; the CLI reads it automatically.
You don't need to run `auth login` for local mode. If the desktop app is closed or hasn't started the bridge yet, the CLI treats local as unavailable.
## Remote backend (cloud API)
Generate a key and store it locally:
Open the desktop app, go to **Integrations > API Keys**, and create a key with the scopes you need (`notes:read`, `notes:write`, `transcriptions:delete`, etc.).
Keys look like `owk_live_abc123...` and are shown once.
```bash theme={null}
openwhispr auth login
```
The CLI prompts for the key and saves it to `~/.openwhispr/cli-config.json` with `0600` permissions.
```bash theme={null}
openwhispr auth status
```
Reports whether a key is configured — a local check only, no network
call. To confirm the cloud API actually accepts it, run
[`openwhispr doctor`](/cli/commands#doctor).
## Logout
```bash theme={null}
openwhispr auth logout
```
Clears the key from `~/.openwhispr/cli-config.json`. The desktop bridge token is not affected.
## Scopes
API-key scopes are enforced server-side. If a command fails with exit code `3` and a "scope" error, the key is missing the required scope — regenerate it from the desktop app with the right boxes ticked.
One exception, and it bites: **`transcriptions:delete` has no checkbox in the desktop app**, so `openwhispr transcriptions delete` fails with a scope error on any key created there. Create that key [through the API](/integrations/agent-setup) instead, naming the scope explicitly.
| Scope | Commands that need it |
| ----------------------- | ---------------------------------------------- |
| `notes:read` | `notes list/get/search`, `folders list` |
| `notes:write` | `notes create/update/delete`, `folders create` |
| `transcriptions:read` | `transcriptions list/get` |
| `transcriptions:delete` | `transcriptions delete` |
Use a personal key (`owk_live_`). The CLI works against your own notes and doesn't address team-space content, so a workspace key (`ow_wks_live_`) won't work here — see [Workspace API keys](/api/workspace-keys).
# Local vs cloud backends
Source: https://docs.openwhispr.com/cli/backends
How the CLI decides whether to talk to the desktop app or the cloud API.
Every CLI command works against one of two backends:
* **Local** — the desktop app's loopback bridge. Fast, offline-capable, mutates SQLite directly via the same code paths the UI uses (audio cleanup, sync hooks, search index, broadcast all run).
* **Remote** — the cloud REST API at `api.openwhispr.com`. Works when the desktop app is closed or you're on a different machine.
## Auto-detection (default)
In auto mode, the CLI picks a backend in this order:
1. The `--local` or `--remote` flag (if passed)
2. The `OPENWHISPR_BACKEND` environment variable (`local`, `remote`, or `auto`)
3. The `backend` key in `~/.openwhispr/cli-config.json`
4. **Auto:** local if the desktop bridge is reachable, otherwise remote if an API key is configured, otherwise an error with guidance
## Force a backend
```bash theme={null}
openwhispr --local notes list
openwhispr --remote notes list
OPENWHISPR_BACKEND=remote openwhispr notes list
```
Or persist the choice:
```bash theme={null}
openwhispr config set backend local
```
## Pointing at a different API
Remote mode talks to `https://api.openwhispr.com` unless you override it, either per-invocation with the `OPENWHISPR_API_BASE` environment variable or persistently:
```bash theme={null}
openwhispr config set api-base https://api.openwhispr.com
```
The environment variable wins over the stored config. The value must start with `http://` or `https://`.
## When to prefer each
| Situation | Backend |
| ------------------------------------------------- | ----------------------- |
| Desktop app open, recent recording | Local — most up-to-date |
| Desktop closed or different machine | Remote |
| You want immediate UI feedback (broadcast events) | Local |
| You don't trust the local SQLite to be in sync | Remote |
| Offline | Local only |
## Capability matrix
| Command | Local | Remote |
| -------------------------------------------- | :---: | :---------------------------: |
| `notes list/get/create/update/delete/search` | ✓ | ✓ |
| `folders list/create` | ✓ | ✓ |
| `transcriptions list/get/delete` | ✓ | ✓ |
| `audio delete` | ✓ | ✗ (cloud doesn't store audio) |
## Mixing local and remote during a meeting
If the desktop app is recording or has just finished a meeting, prefer `--local`. The local SQLite is authoritative until sync reconciles. Running destructive commands against remote during this window can drift the two copies until the next sync pulls them back together.
# Command reference
Source: https://docs.openwhispr.com/cli/commands
Every OpenWhispr CLI command, organized by noun.
The CLI uses noun-verb syntax (`notes list`, not `list-notes`) — same convention as `gh`, `kubectl`, `aws`, `stripe`.
## Global flags
| Flag | Effect |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--local` | Force the local desktop bridge backend |
| `--remote` | Force the remote cloud API backend |
| `--format ` | Output format, per command. Supported values vary (`json`, `table`, `markdown`, `text`). Default depends on TTY: human-readable in a terminal, JSON when piped. Not all commands accept this flag — `notes create`, `notes update`, and `folders create` always emit full JSON. |
| `-h, --help` | Show command help |
| `-V, --version` | Print CLI version |
## Notes
```bash theme={null}
openwhispr notes list [--folder ] [--limit N] [--format json|table]
openwhispr notes get [--transcript] [--format json|markdown]
openwhispr notes create --content | --content-file
[--title ] [--folder ]
openwhispr notes update [--content ] [--folder ] [--title ]
openwhispr notes delete [--dry-run] [--format json|table]
openwhispr notes search [--limit N] [--format json|table]
```
For notes with an AI-enhanced version (e.g. meeting notes), `notes get`'s markdown output shows the enhanced note when one exists, matching the desktop app. The raw fields are always available via `--format json` (`content`, `enhanced_content`). Pass `--transcript` to output only the note's transcript — as speaker-labeled markdown, or as `{ "transcript": "..." }` with `--format json`.
## Folders
```bash theme={null}
openwhispr folders list [--format json|table]
openwhispr folders create --name [--sort-order ]
```
## Transcriptions
```bash theme={null}
openwhispr transcriptions list [--limit N] [--format json|table]
openwhispr transcriptions get [--format json|text]
openwhispr transcriptions delete [--dry-run] [--format json|table]
```
`--format text` returns the plain transcript body. SRT and VTT subtitle formats aren't currently exposed by the CLI — use `--format json` and post-process the segment data if you need timestamped subtitles.
## Audio
```bash theme={null}
openwhispr audio delete [--format json|table]
```
Local-only. Deletes the audio file for a **dictation** transcription (meeting transcripts have no audio to delete — only their text is captured). The cloud API doesn't store audio at all, so running with `--remote` exits with a "not supported" error.
## Auth
```bash theme={null}
openwhispr auth login # prompts for API key, stores in ~/.openwhispr/cli-config.json
openwhispr auth logout
openwhispr auth status
```
## Config
```bash theme={null}
openwhispr config get
openwhispr config set backend auto|local|remote
openwhispr config set api-base https://api.openwhispr.com
```
## Doctor
```bash theme={null}
openwhispr doctor [--format json|table]
```
Reports which backends are reachable and exits non-zero if neither is.
## Exit codes
| Code | Meaning |
| ---- | ---------------------------------------------------------------- |
| 0 | Success |
| 1 | User error (bad arguments, missing required flag) |
| 2 | Backend unreachable (app not running, API unreachable) |
| 3 | Authentication failure (missing/invalid key, insufficient scope) |
| 4 | Not found (no such note/transcription/folder) |
# CLI install
Source: https://docs.openwhispr.com/cli/install
Install the OpenWhispr CLI and verify it can reach your data.
The OpenWhispr CLI (`@openwhispr/cli`) is a single binary that operates against either the local desktop app or the cloud API.
## Requirements
* Node.js 20 or later
* Either the [OpenWhispr desktop app](/index) running locally, or an API key for cloud access
## Install
```bash npm theme={null}
npm install -g @openwhispr/cli
```
```bash pnpm theme={null}
pnpm add -g @openwhispr/cli
```
```bash bun theme={null}
bun add -g @openwhispr/cli
```
## Verify
```bash theme={null}
openwhispr --version
```
Then check which backends are reachable:
```bash theme={null}
openwhispr doctor
```
The `doctor` command reports the local desktop bridge and remote API independently. Exit code is `0` if at least one backend is reachable, `2` otherwise.
## Next steps
* [Authenticate](/cli/authentication) for cloud access
* Learn how the CLI [picks a backend](/cli/backends)
* Browse the full [command reference](/cli/commands)
# Contributing
Source: https://docs.openwhispr.com/contributing
How to contribute to OpenWhispr.
We welcome contributions. Here's how to get started.
## Setup
```bash theme={null}
git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr
npm install
npm run dev
```
Use Node.js 24 (pinned in `.nvmrc`). Running `npm install` with a different major version produces an incompatible lockfile.
## Development scripts
| Command | Description |
| ------------------------------ | -------------------------------------------------- |
| `npm run dev` | Start with hot reload |
| `npm start` | Production mode |
| `npm run build:renderer` | Build the React app |
| `npm run pack` | Build unsigned app for testing |
| `npm run lint` | Run ESLint |
| `npm run format` | Format with Prettier |
| `npm run compile:native` | Compile native helpers (Globe key, paste binaries) |
| `npm run download:whisper-cpp` | Download whisper.cpp for current platform |
## Architecture
The app has two windows sharing one React codebase:
* **Main window** — minimal overlay for dictation controls
* **Control panel** — full settings, history, notes, and integrations
Key layers:
* **Main process** (`main.js`) — Electron main, IPC handlers, database
* **Preload** (`preload.js`) — secure bridge between main and renderer
* **Renderer** — React 19, TypeScript, Tailwind CSS v4, shadcn/ui
## Tech stack
* React 19, TypeScript, Tailwind CSS v4, Vite
* Electron 41 with context isolation
* better-sqlite3 with FTS5
* shadcn/ui with Radix primitives
* whisper.cpp + sherpa-onnx for local transcription
## Submitting changes
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Run `npm run lint` before committing
4. Open a pull request
## Guidelines
* Use TypeScript for new React components
* Follow existing patterns in `src/helpers/` and `src/hooks/`
* All new UI strings must use the i18n system (10 languages supported)
* Test on your target platform before submitting
* Add translation keys to all language files in `src/locales/`
# FAQ
Source: https://docs.openwhispr.com/faq
Frequently asked questions about OpenWhispr.
Yes. OpenWhispr is open source and free to use. The free plan is free forever and includes 2,000 words per rolling 7 days of cloud transcription; local processing has no limits at all. Pro plans start at \$8/month for unlimited cloud transcription. See [Plans and limits](/help/plans-and-limits).
Use **local processing** for privacy and offline use. Use **cloud processing** for speed and convenience. See [cloud vs local](/guides/cloud-vs-local) for a detailed comparison.
Yes. The MIT license allows commercial use, modification, and distribution.
OpenWhispr supports 100+ languages for transcription including English, Spanish, French, German, Chinese, Japanese, and more. Which languages are available depends on the model you use — see [Plans and limits](/help/plans-and-limits). Set your preferred language in settings or use auto-detect.
Notes are stored locally in SQLite. Cloud sync is optional — when signed in to OpenWhispr Cloud, notes are backed up to the cloud but local storage remains the primary copy.
With local processing, audio never leaves your device. With cloud processing, audio is sent to the transcription provider (OpenAI, Groq, etc.). OpenWhispr doesn't collect analytics or telemetry.
You control it. Under **Settings**, data retention can automatically delete saved audio and transcripts after a period you choose (1, 7, 14, 30, 60, or 90 days). By default, audio recordings are removed after 30 days and transcripts are kept until you delete them. You can also turn off saving audio and transcripts entirely. Every setting, and how to use retained audio to recover a failed dictation, is in [I lost a dictation](/help/fix/recover-a-lost-dictation).
No. OpenWhispr uses NSEvent monitors instead of CGEvent taps, so Input Monitoring permission is not required. Only Microphone and Accessibility permissions are needed (plus Screen Recording for meetings).
OpenWhispr detects meetings automatically (Zoom, Teams, FaceTime, and browser-based calls). Audio is transcribed in real time with speaker labels, and Google Calendar can optionally fill in meeting titles and attendees. See [meeting transcription](/guides/meeting-transcription) for details.
# AI agent
Source: https://docs.openwhispr.com/guides/agent-mode
Speak an instruction instead of text, or open a chat that can work with your notes.
OpenWhispr has an AI agent you reach two different ways, depending on what you
want:
* **The voice agent** types the *result* of an instruction at your cursor. Say
"write a short thank-you note" and the note appears.
* **The chat agent** opens a conversation window that can search your notes,
write and edit them, search the web, and read your calendar.
They share settings but behave quite differently.
Press a key, speak an instruction, get the result typed at your cursor.
A conversation overlay with tools that work on your notes.
Saying its name during dictation hands the rest over to the agent.
Dictation, agent, translation and meetings, told apart.
## Two ways to reach the voice agent
This is the part that surprises people. The voice agent runs when either:
1. You press the **Voice Agent Hotkey**, or
2. You **say the agent's name** at the start of an ordinary dictation.
The second is on by default, and the default name is **OpenWhispr** — so it's
possible to trigger the agent without meaning to. [Your agent's
name](/help/agent/agent-name) covers how the detection works and how to rename
or disable it.
## Where the settings live
Everything except the hotkeys is under **Settings** → **Language Models** under
**AI Models**:
| Tab | Controls |
| --------------- | ----------------------------------------------- |
| **Voice Agent** | Enable it, name it, choose its model and prompt |
| **Chat** | The chat agent's model and system prompt |
The hotkeys themselves are under **Settings** → **Hotkeys** under **App** —
**Voice Agent Hotkey** and **Chat Agent Hotkey** are separate entries.
## Where it can run
Both agents run on whichever provider you choose: OpenWhispr Cloud with no
setup, your own API key with OpenAI, Anthropic, Gemini or Groq, a local model
on your own device, a self-hosted endpoint, or an enterprise provider such as
AWS Bedrock, Azure OpenAI or Google Vertex.
A local model keeps everything on your machine. See [cloud vs
local](/guides/cloud-vs-local) and [enterprise providers](/guides/enterprise).
## Related
* [It answers me instead of typing](/help/fix/it-answers-instead-of-typing)
* [How dictation works](/guides/dictation)
# Cloud vs local processing
Source: https://docs.openwhispr.com/guides/cloud-vs-local
Choose between cloud, bring-your-own-key, enterprise, and fully local processing.
OpenWhispr gives you several ways to process speech and AI text. Pick the
combination that fits your workflow.
## OpenWhispr Cloud
Sign in with Google, Apple (macOS), Microsoft, or email — no API keys needed.
* **Free plan** — free forever, 2,000 words per rolling 7 days
* **Pro plan** — unlimited transcriptions
* Fastest option, no model downloads
* Audio is processed on OpenWhispr's servers
## Bring your own key (BYOK)
Use your own API keys from third-party providers:
| Provider | What you get |
| ------------------------- | -------------------------------------------------------------------- |
| OpenAI | Transcription plus GPT models for AI actions |
| Groq | Fast Whisper transcription plus hosted reasoning models |
| xAI | Grok speech-to-text |
| Mistral | Voxtral transcription model |
| Tinfoil | Confidential, attested transcription (realtime and uploaded audio) |
| Corti | Clinical-grade transcription plus EU-hosted AI cleanup and reasoning |
| OpenRouter | 300+ AI agent and text-enhancement models through one key |
| Anthropic / Google Gemini | AI agent and text enhancement models |
Enter your API keys in **Settings** under each provider section.
## Enterprise
Point OpenWhispr at your organization's cloud LLM account — no model proxy and, with managed access, no personal API keys or CLI setup.
* **Amazon Bedrock** — centrally managed OIDC federation or the existing AWS profile/key flow
* **Azure OpenAI** — centrally managed Microsoft Entra federation or the existing API-key flow
* **GCP Vertex AI** — planned
With managed access, IT assigns the employee through SCIM and chooses the
models. The employee signs in with company SSO and can use the configured
features immediately. Short-lived credentials remain in the desktop app's main
process, while AI text prompts and responses travel directly between the device
and the organization's cloud account. Transcription audio continues to follow
the speech-to-text setting for that activity.
See [enterprise providers](/guides/enterprise) for setup.
## Local processing
Download a model and process everything on your device. Audio never leaves your machine.
* **Whisper** — multiple model sizes from 75 MB to 3 GB
* **NVIDIA Parakeet & Nemotron** — fast offline and streaming models, English and multilingual (\~630–680 MB)
* Works offline after initial model download
* See [local models](/guides/local-models) for setup
## Comparison
| | Cloud | BYOK | Enterprise | Local |
| -------- | --------------------- | ----------------------- | -------------------------------------------------------------------- | ---------------- |
| Setup | Sign in | Add API key | IT-managed SSO, or manual cloud credentials | Download model |
| Speed | Fast | Fast | Fast | Depends on model |
| Privacy | Audio sent to servers | Audio sent to provider | AI text sent to your cloud; audio follows its speech-to-text setting | Fully private |
| Internet | Required | Required | Required | Not needed |
| Cost | Free tier or Pro plan | Your provider's pricing | Your cloud account's pricing | Free |
# Make OpenWhispr yours
Source: https://docs.openwhispr.com/guides/custom-dictionary
Teach OpenWhispr your vocabulary, set up snippets, pick your microphone, and find any setting.
Four things make OpenWhispr fit the way you actually work: the words it should
always get right, the phrases you shouldn't have to say twice, the microphone it
listens to, and knowing where the settings are.
## Start here
Names, jargon and acronyms, so they're transcribed correctly.
Say a short trigger, get the full text.
Which input device is used, and why built-in often wins.
A map of all nine settings sections.
## Dictionary or snippet?
Both live under **Dictionary** in the sidebar, on their own tabs, and they solve
different problems:
| Use a **dictionary** entry | Use a **snippet** |
| ------------------------------------ | -------------------------------------------------- |
| A word keeps being transcribed wrong | You want a short phrase to expand into longer text |
| It's a hint to the model | It's an exact substitution |
| "Siobhán" comes out as "Siobhán" | `cal link` becomes your booking URL |
## Related
* [Improve accuracy](/help/dictation/improve-accuracy) — the wider set of levers
* [Cleanup and formatting](/help/dictation/cleanup)
* [Choosing a shortcut](/help/dictation/choosing-a-shortcut)
# How dictation works
Source: https://docs.openwhispr.com/guides/dictation
Speak into any app and have your words typed at the cursor — and the settings that control it.
OpenWhispr listens when you press a key, transcribes what you say, and types it
wherever your cursor is. It works in any app — email, chat, a code editor, a
document. Nothing to copy, no window to switch to.
## How it works
1. **Press your hotkey.** On macOS that's the **Globe** (Fn) key by default;
on Windows **Ctrl+Win**, on Linux **Ctrl+Super**.
2. **Speak.** The panel shows it's recording.
3. **Press it again to stop** — or hold the key throughout and release, if you've
set it to [hold](/help/dictation/hold-or-tap).
4. **The text is transcribed, tidied, and pasted** at your cursor.
Step 4 does two things worth knowing about separately: transcription turns audio
into words, and [cleanup](/help/dictation/cleanup) tidies those words before
they land. Cleanup is on by default, which is why dictation reads like writing.
## Set it up the way you want
Five separate shortcuts, what each starts, and how to change or unbind them.
Press to start and stop, or hold while you speak.
The rules, the reserved combinations, and what to use instead.
Automatic pasting, permissions, and keeping a clipboard copy.
What gets tidied before pasting, and how to switch it off.
Set the language you speak, or let it detect one.
Dictate in one language, paste in another.
Four things that measurably improve results.
## It isn't only dictation
The same voice, on a different shortcut, can carry out an instruction rather
than be typed out. If you're getting answers instead of your words, that's the
voice agent — [the four things your voice can start](/help/agent/voice-modes)
tells them apart.
## When something goes wrong
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
* [My text isn't pasting](/help/fix/text-not-pasting)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [Recovering a lost dictation](/help/fix/recover-a-lost-dictation)
# Enterprise providers
Source: https://docs.openwhispr.com/guides/enterprise
Use your organization's Amazon Bedrock or Azure OpenAI account with managed company access or the existing manual setup.
Enterprise mode sends AI cleanup and agent requests directly from the OpenWhispr desktop app to your organization's cloud account. OpenWhispr does not proxy the prompt or response.
| Provider | Centrally managed | Manual setup |
| -------------- | ----------------- | ------------------------------------------------- |
| Amazon Bedrock | Available | AWS profile, CLI credential chain, or access keys |
| Azure OpenAI | Available | Azure API key |
| GCP Vertex AI | Planned | Google application credentials |
## Managed company access
Managed access is available to active Enterprise workspaces. IT connects company SSO and SCIM, establishes workload trust in AWS or Microsoft Entra, validates it in the admin portal, and chooses the permitted models once. Business and Pro workspaces continue using their ordinary sign-in and manual provider flows; stale Enterprise SSO settings are not enforced after a downgrade.
For an employee, the flow is:
1. Open OpenWhispr and choose company SSO.
2. Finish sign-in in the browser.
3. The workspace and team assignments appear automatically.
4. Bedrock or Azure OpenAI is already selected for every feature the administrator configured.
There is no AWS CLI login, cloud API key, role ARN, tenant ID, or model name for the employee to enter. The desktop exchanges a short-lived OpenWhispr assertion for temporary access and keeps cloud credentials in memory only.
See [managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai) for the complete administrator setup.
## Existing manual setup
The original enterprise flow remains available for individual testing and gradual migrations. An employee can use an AWS SSO profile, the standard AWS credential chain, AWS access keys, or an Azure API key when the workspace administrator allows manual setup.
Open **Settings > AI Models > Language Models**, choose a feature tab, then select **Enterprise** and the provider.
Enter an AWS profile or access keys, region, and model ID. If the profile uses AWS IAM Identity Center, run `aws sso login --profile ` before testing the connection.
OpenWhispr resolves the profile through the standard AWS SDK credential chain.
Model IDs are region-aware: the suggested list uses the cross-region inference profile prefix (`us.`, `eu.`, or `apac.`) that matches your selected region, and changing the region rewrites an already-picked model to the new geography. Select **Browse all models** to load your account's full Bedrock catalog live — resolved against your own credentials and region, so a picked model is always invocable — or enter a custom model ID for anything not in the list.
Enter the Azure OpenAI endpoint, API key, API version, and deployment name,
then test the connection. Existing manual endpoints and dated API versions
remain supported; the stricter public-resource-origin contract applies only
to centrally managed access.
### Suggested Bedrock models
Enable model access for these in the AWS Bedrock console before selecting them. Managed workspaces get their allowlist from the administrator instead.
| Model | Bedrock ID | Use case |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
| Claude Fable 5 | `us.anthropic.claude-fable-5` | Most capable Claude model (Mythos-class) — best for the hardest Agent Mode tasks |
| Claude Haiku 4.5 | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | Fast, cheap — recommended default for text cleanup |
| Claude Sonnet 5 | `us.anthropic.claude-sonnet-5` | Balanced text cleanup and summarization |
| Claude Opus 4.8 | `us.anthropic.claude-opus-4-8` | Complex text cleanup and summarization |
| GPT-OSS 120B | `openai.gpt-oss-120b-1:0` | Open-weight OpenAI model |
| DeepSeek V3.2 | `deepseek.v3.2` | Open-weight reasoning model |
| Qwen3 Next 80B | `qwen.qwen3-next-80b-a3b` | Open-weight, multilingual |
**Managed by default** keeps existing manual users on their chosen setup while giving unconfigured employees the company provider. **Managed required** disables the manual path for the workspace.
## Features and defaults
Enterprise models are chosen per capability. A managed administrator supplies a default for all five so a new employee does not see an incomplete setup.
| Feature | What it powers |
| ----------------- | ---------------------------------------------------- |
| Dictation cleanup | Tidying dictated text |
| Dictation agent | The voice agent that answers instead of transcribing |
| Note formatting | Structuring notes after a recording |
| Note chat | Chatting with and reasoning over notes |
| Translation | Translating dictated text |
In manual mode, changing one capability does not change the others.
## Credential handling
Managed AWS credentials last up to 15 minutes. Azure tokens use the expiry returned by Microsoft. They are held in the desktop main process, are never exposed to the page interface, and are cleared when the account, workspace, provider configuration generation, or authorization changes.
Manual keys entered in OpenWhispr are encrypted through Electron `safeStorage`, backed by Keychain on macOS, DPAPI on Windows, and libsecret on Linux. They are never sent to OpenWhispr's servers.
On Linux without an installed and unlocked keyring, Electron can fall back to plaintext secret storage. Use managed access or configure a system keyring on managed Linux devices.
## Troubleshooting
| Message | Fix |
| ---------------------------------- | ------------------------------------------------------------------------- |
| Company SSO is required | Sign out, then choose company SSO rather than email or social login |
| Directory assignment required | Ask IT to activate your SCIM assignment |
| AWS SSO session expired | Manual mode only: run `aws sso login --profile ` |
| AWS cannot assume the role | Ask IT to check the managed OIDC trust policy |
| Microsoft identity exchange failed | Ask IT to check the Entra federated credential |
| Model or deployment is not allowed | Choose one supplied by your workspace administrator |
| Model access not enabled | Enable that model for your account and region in the AWS Bedrock console |
| Model not found | Check the ID format and that the model is offered in your selected region |
| Invalid AWS credentials | Manual mode only: recheck the access key and secret in AWS IAM |
| Rate limited | You hit a Bedrock or Azure quota — wait a moment and retry |
The connection test surfaces these with copy-paste remediation commands where applicable.
## Related
* [Provision people and teams with SCIM](/help/it/scim-provisioning)
* [Cloud vs local processing](/guides/cloud-vs-local)
* [Where your voice and text go](/help/privacy/where-your-data-goes)
# Local models
Source: https://docs.openwhispr.com/guides/local-models
Set up Whisper, NVIDIA Parakeet, and Nemotron for private, offline transcription.
Local processing keeps your audio on your device. OpenWhispr supports two speech recognition engines: whisper.cpp and sherpa-onnx (NVIDIA Parakeet & Nemotron).
## OpenAI Whisper (via whisper.cpp)
The default local engine. Choose a model based on your needs:
| Model | Size | Speed | Quality |
| ------ | -------- | -------- | ------------------ |
| tiny | \~75 MB | Fastest | Basic |
| base | \~142 MB | Fast | Good (recommended) |
| small | \~466 MB | Moderate | Better |
| medium | \~1.5 GB | Slow | High |
| large | \~3 GB | Slowest | Best |
| turbo | \~1.6 GB | Fast | Good |
### Setup
1. Open **Settings**, choose **Speech-to-Text** under **AI Models**, then the tab for the mode you're setting up — **Dictation**, **Note Recording** or **Audio Upload**. Each keeps its own engine choice.
2. Choose **Local**, then select a Whisper model
3. Click **Download** — models are stored in `~/.cache/openwhispr/whisper-models/`
The whisper.cpp binary is bundled with OpenWhispr. No Python or additional runtime needed.
### GPU acceleration
Local Whisper can run on your GPU for much faster transcription:
* **macOS** — Metal acceleration is built in on Apple Silicon, no setup needed
* **NVIDIA (Windows/Linux)** — one-click CUDA runtime download from the GPU card in the model picker
* **AMD / Intel (Windows/Linux)** — one-click Vulkan runtime download from the same GPU card, covering Radeon and Arc/integrated GPUs
If the GPU runtime fails to start (unsupported GPU, out of VRAM), OpenWhispr automatically falls back to CPU with an in-app notice — transcription keeps working.
## NVIDIA Parakeet & Nemotron (via sherpa-onnx)
A faster alternative to Whisper, especially on lower-end hardware.
| Model | Size | Languages |
| --------------------------------- | -------- | ------------------------------------- |
| parakeet-tdt-0.6b-v3 | \~680 MB | 25 languages |
| parakeet-unified-en-0.6b | \~631 MB | English (state-of-the-art accuracy) |
| nemotron-speech-streaming-en-0.6b | \~632 MB | English (streaming) |
| nemotron-3.5-asr-streaming-0.6b | \~650 MB | 15 languages, auto-detect (streaming) |
### Setup
1. Open **Settings**, choose **Speech-to-Text** under **AI Models**, then the tab for the mode you're setting up
2. Choose **Local**, then switch the provider to **NVIDIA Parakeet**
3. Download the model
Parakeet's offline models use INT8 quantized ONNX models for efficient CPU inference. The Nemotron models are streaming models: dictation is decoded live over one persistent connection and the text is committed the moment you stop speaking — no second decoding pass — and with the live preview enabled, partial text updates as you speak. If the stream fails, transcription automatically falls back to the standard record-then-transcribe path.
## Which to choose
* **Parakeet** — best for speed, lower-end hardware, or when you need multilingual support
* **Whisper** — best for quality, especially with the `medium` or `large` models
## Disk management
Remove downloaded models anytime from **Settings** → **System** → **Data Management** → **Model cache**, using **Clear cache**. **Open** shows you the folder first. Models can be re-downloaded when needed — see [where your files live](/platform/where-your-files-live).
# How meetings work
Source: https://docs.openwhispr.com/guides/meeting-transcription
Record a call, get a transcript with speaker labels, and find it again afterwards.
OpenWhispr can record a meeting, transcribe it as people talk, label who said
what, and save the result as a searchable note. It doesn't join the call as a
bot and nobody else sees it running.
## Start here
Start a recording, watch it transcribe, and find the note afterwards.
What makes the take-notes prompt appear, and how to turn it off.
Who said what, how to correct it, and how to switch it off.
Why recording other participants is separate from your microphone.
Titled notes, attendee lists, and one-click join.
Read meetings straight from Calendar.app on macOS.
What each plan includes.
## How it works, briefly
You start a recording — from the prompt OpenWhispr shows you, or with the
**Meeting Mode Hotkey**. It captures your microphone and, with the right
permission, the audio your computer is playing, which is how the other
participants get recorded. Text appears live. Speaker labels are assigned as it
goes and refined once the call ends. The finished note lands in your **Meetings**
folder.
Meeting recording keeps its own transcription engine, set on the
**Note Recording** tab of **Settings → Speech-to-Text**, so you can run meetings
locally while dictating through the cloud, or the other way round.
## When something's wrong
* [Meeting audio isn't captured](/help/fix/meeting-audio-not-captured) — you got
your own voice and nobody else's
* [My microphone isn't working](/help/fix/microphone-not-working)
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
# How notes work
Source: https://docs.openwhispr.com/guides/notes
Where your dictations, meetings and uploads are kept — organising, searching, syncing, exporting and sharing them.
Everything OpenWhispr transcribes is saved as a note: dictations, meeting
recordings, uploaded audio, and anything you type yourself. Notes live on your
own machine first — syncing, sharing and exporting are all things you turn on.
## Start here
Folders, the ones OpenWhispr makes for you, and the one-way move into a team space.
Find a note by its words or by what it was about.
Turn on cloud backup, and what syncs even when it's off.
Save one note as Markdown, or mirror every note to disk.
Links, email invitations, and who can see what.
Shared spaces, roles and invitations.
## Where notes come from
| Source | Notes |
| -------------- | ----------------------------------------------------------------------------------------- |
| **Dictation** | Saved automatically as you dictate |
| **Meetings** | The recording and its transcript — see [How meetings work](/guides/meeting-transcription) |
| **Uploads** | Audio and video files, or a URL to fetch |
| **The editor** | Anything you write yourself |
| **The API** | Created programmatically — see the [REST API](/api/overview) |
## Importing audio
The **Upload** view turns existing recordings into notes. Drag in files
(MP3, WAV, M4A, WebM, OGG, FLAC, AAC), or paste a YouTube or direct media URL to
fetch and transcribe it. You can queue several at once and keep working while
they process.
File size limits depend on how the audio is processed — no limit with local
models, 25 MB on the Free plan or with your own API key, and 500 MB on a paid
plan using OpenWhispr Cloud. [Plans and limits](/help/plans-and-limits) has the
detail.
Uploads can be transcribed with speaker detection too, using the same on-device
models the meeting recorder uses — see
[speaker labels](/help/meetings/speaker-labels).
## Working with a note
Each note has an editor, AI actions that clean up or summarise what's there, and
its own chat panel for asking questions about that note's content. The
[chat agent](/help/agent/chat-agent) searches across all of them at once.
# Team spaces
Source: https://docs.openwhispr.com/guides/team-spaces
Shared spaces where a workspace's notes live — how teams grant access, what syncing and conflicts look like, and what happens when access ends.
Team spaces bring collaboration into the notes sidebar: shared containers of
folders and notes that sync between everyone with access, listed under
**TEAM SPACES**. Your **Personal** space sits under **PRIVATE SPACES** above
them, and stays yours alone — *"Only you can see your Personal space."*
Access to a team space isn't granted person by person. It flows through
**teams** — named groups of workspace members. Assign a team to a space and
everyone in that team can open it; workspace owners and admins can open every
space regardless.
Team spaces need a **paid workspace plan** — the workspace's own subscription,
separate from anyone's personal plan. A Free workspace says so when you try:
see [billing for a team](/help/account/workspace-billing).
## The pieces
| | What it is | Where you manage it |
| -------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
| **Workspace** | Your organisation: members, seats, billing | **Settings** → **Workspace** under **Account** |
| **Team** | A named group of workspace members | The **Team spaces** tab of **Workspace** settings |
| **Team space** | A shared area of folders and notes that one or more teams can access | The notes sidebar |
## Creating a team space
Spaces are created from the notes screen: the **+** button in the sidebar's
**TEAM SPACES** header (**New team space**). Workspace owners and admins can
create them.
The dialog — *"A shared area inside a workspace that one or more teams can
access"* — asks for an emoji and a name, then which **Teams** get access.
No team yet? Create one right there with **New team**.
There's no way to create a space from Settings — the **Team spaces** tab in
**Workspace** settings manages teams, not spaces.
## Teams
Open **Settings** → **Workspace** under **Account** and choose the
**Team spaces** tab: *"Groups of workspace members that grant access to team
spaces."*
* **New team** creates one — name it and add members.
* Each team's row shows its member count and *"Grants access to N spaces."*
* **Members** opens the team's roster: add or remove people, or **Leave team**
yourself — *"You'll lose access to the spaces this team is assigned to
unless another team includes you."*
* Deleting a team archives it: *"Its members lose any access it granted."*
There is no "leave a space" — membership works per team, so to walk away from
a space you leave the teams that grant it.
## A space's access
Open **Teams & members…** from the space's menu in the sidebar:
* **Add a team to this space**, or remove one. The app warns before you cut
anyone off: removing the last team means *"only workspace admins keep
access,"* and changes to a team *"also apply to N other spaces it has
access to."*
* Per team, set **Space access** to **Member** or **Admin**. Members read and
write the space's folders and notes; a team's admins manage the space
*"only when its access is set to Admin."*
Space admins — and workspace owners and admins, who always count — can
**Rename**, **Change emoji**, and **Delete space**. Deleting asks you to type
the space's name first, and it deletes the space for everyone: *"Its teams
remain, but members lose access to all of its folders and notes."*
## Inviting someone new
Workspace invitations live in **Settings** → **Workspace** under **Account**,
in the **Members** tab: enter an email and pick a workspace role — **Admin**
(*"Manages members and billing"*) or **Member** (*"Uses the workspace"*).
Invite from inside a team's roster — or a space's **Teams & members** dialog —
and that team comes attached: on accepting, the invitee is told *"You'll join
N team spaces,"* and those spaces' content syncs down in the background.
## Everyday work
* Drag notes and folders into a space to share them — but know that it's a
**one-way move**: everyone in the space can then view and edit them, and
*"Notes can't be moved out of a team space."*
[Organise notes with folders](/help/notes/organise-with-folders) covers
this rule in full.
* Everything stays local-first: the on-device database remains the source of
truth, and each space syncs in the background — see
[sync notes across devices](/help/notes/sync-across-devices).
* If a teammate's version of a note arrives while you have unpushed edits, a
banner appears — *"A newer version of this note exists,"* naming the editor
when it can (*"Edited by …"*). **Refresh** takes their copy; **Keep
editing** stays on yours.
## Losing access
Access is checked on every sync. If you're removed — from a team, or the team
from a space — the space's synced notes are removed from your device, with a
notice that you no longer have access. Anything you changed that never synced isn't
lost: *"your unsynced edits were saved as a copy in your Personal space."*
## Sharing a note on the web
Publishing a single note to the web is a separate, per-note feature — an email
invitation or a link with a visibility you choose, available on any paid plan.
[Share a note](/help/notes/share-a-note) covers it. Inside a team space the
note's audience is the space itself: the share dialog shows **Everyone in this
team space**.
## Related
* [Share a note](/help/notes/share-a-note)
* [Organise notes with folders](/help/notes/organise-with-folders)
* [Billing for a team](/help/account/workspace-billing)
* [Seats — adding, removing and what counts](/help/account/seats)
* [Sync notes across devices](/help/notes/sync-across-devices)
# Cancelling your subscription
Source: https://docs.openwhispr.com/help/account/cancel-your-subscription
How to cancel, what happens to your notes and transcriptions, and what keeps working afterwards.
You can cancel yourself, in about thirty seconds, and you don't have to talk to
anyone to do it.
Open **Settings**, choose **Plans & Billing** under **Account**, and click
**Manage Billing**. That opens your billing page at Stripe, where you'll find
the option to cancel your subscription. Stripe shows you exactly what will
happen, and when, before you confirm.
If you'd rather we did it, email
[support@openwhispr.com](mailto:support@openwhispr.com) from the address on your
account and we'll cancel it for you the same day.
## What happens to your stuff
Cancelling stops future payments. It doesn't delete anything.
* **Your notes and transcriptions stay.** Nothing is erased when a subscription
ends. If you want your data actually removed, that's
[deleting your account](/help/account/delete-your-account) — a separate,
deliberate action.
* **Local dictation keeps working, with no limits.** On-device transcription
runs on your own machine, so it doesn't depend on a subscription at all. This
is the part people are most often surprised by: you don't lose OpenWhispr, you
go back to the Free plan.
* **Your own API keys keep working.** BYOK is unlimited on every plan, including
Free.
* **OpenWhispr Cloud goes back to the Free allowance** — 2,000 words per rolling
7 days. See [Plans and limits](/help/plans-and-limits).
## If you're cancelling because something's broken
Please tell us first — [support@openwhispr.com](mailto:support@openwhispr.com).
We'd genuinely rather fix the problem than lose you over it, and a fair number
of cancellations we see turn out to be a setting or a known bug with a
workaround. If we can't fix it, we'll cancel you on the spot and you've lost
nothing but one email.
## Refunds
Cancelling and getting money back are two different things — cancelling stops
the next payment, it doesn't return the last one. If you want a refund as well,
ask us and we'll sort it out: see [Refunds](/help/account/refunds).
## FAQ
No. Cancelling stops future charges. Stripe will confirm the date your paid
access runs to on the cancellation screen.
Yes, and nothing is lost in the meantime. Upgrade again from **Settings →
Plans & Billing** whenever you like.
That button only appears if you're paying for OpenWhispr personally. If your
plan comes from a team workspace, billing is managed by whoever owns it — the
Plan section will name them. If you're on a free month from a referral, there
isn't a subscription to cancel yet.
No. Your account and everything in it stays. See
[Deleting your account](/help/account/delete-your-account) if that's what you
want.
## Related
* [Refunds](/help/account/refunds)
* [Deleting your account](/help/account/delete-your-account)
* [Cloud vs local processing](/guides/cloud-vs-local)
# Changing your email address
Source: https://docs.openwhispr.com/help/account/change-your-email
How to move your account — and your subscription — to a different email address.
Email us at [support@openwhispr.com](mailto:support@openwhispr.com) from the
address currently on the account, tell us the new one, and we'll move it.
There's no way to do this from inside the app yet. We'd rather say that plainly
than have you search Settings for a button that doesn't exist. It's on our list.
## What moves with it
Everything. Your notes, transcriptions, settings, and your subscription all stay
attached to the same account — only the address you sign in with changes. You
won't be charged again and you don't need to resubscribe.
## Leaving a company, or moving from work to personal
This is the most common reason people ask, and it works the same way: send us
both addresses and we'll switch it over. Worth doing **before** you lose access
to the old mailbox, since we email the current address to confirm the change is
really you.
If you can no longer receive mail at the old address, tell us — we can still
help, we'll just need a bit more to confirm you're the account holder, such as
the last four digits of the card or the date of a recent payment.
## FAQ
You can, but you'd leave your notes and transcriptions behind on the old
account and start a new subscription. Moving the address keeps everything.
Invoices already issued keep the details they were issued with. If you need
one reissued, see
[Invoices and receipts](/help/account/invoices-and-receipts).
Yes — email us and we'll sort it. Tell us how you sign in so we know what
we're moving.
## Related
* [Managing your subscription](/help/account/manage-your-subscription)
* [Invoices and receipts](/help/account/invoices-and-receipts)
* [Deleting your account](/help/account/delete-your-account)
# Changing your plan
Source: https://docs.openwhispr.com/help/account/change-your-plan
Upgrading, downgrading, and switching between monthly and annual billing — including what you're charged today.
You can move between plans whenever you like, and the change takes effect
immediately. Open **Settings**, choose **Plans & Billing** under **Account**,
and pick the plan you want.
When you switch, OpenWhispr shows you what you'll be charged today before you
confirm — you're not agreeing to an unknown number.
## What you're charged when you switch
Billing is prorated, which means you only pay for what you use:
* **Upgrading mid-cycle** — you're charged the difference between what you've
already paid and the new plan, for the days left in the current period. Not a
full month on top.
* **Downgrading mid-cycle** — the unused portion of what you've paid becomes
credit, and it comes off your next invoice rather than being refunded to your
card.
* **Monthly to annual** — the same maths. Annual works out cheaper: Pro is
\$8/month or \$80/year, and Business is \$20/user/month or \$200/user/year, so a
year up front costs you ten months rather than twelve.
The figure shown before you confirm is the amount for today. Your regular
billing date stays where it is.
## The plans
| | Free | Pro | Business | Enterprise |
| ---------------------------------- | ------------------------------ | --------------------- | --------------------------------- | ---------- |
| Price | \$0 | \$8/month · \$80/year | \$20/user/month · \$200/user/year | Custom |
| OpenWhispr Cloud | 2,000 words per rolling 7 days | Unlimited | Unlimited | Unlimited |
| Local models and your own API keys | Unlimited | Unlimited | Unlimited | Unlimited |
The full breakdown, including file size limits and meeting allowances, is in
[Plans and limits](/help/plans-and-limits).
## Downgrading to Free
There's no separate "downgrade to Free" — that's
[cancelling](/help/account/cancel-your-subscription). You keep unlimited local
dictation and your own API keys, and OpenWhispr Cloud returns to the Free
allowance.
## FAQ
Your notes and transcriptions all stay. What changes is the allowance on
OpenWhispr Cloud and the file size you can upload to it — see
[Plans and limits](/help/plans-and-limits).
It usually catches up within a few seconds of Stripe confirming the change.
If it hasn't after a minute, close and reopen Settings. If it's still wrong,
tell us — that's a bug, not something you should have to work around.
Yes — Business is \$200/user/year. For teams, seats are managed in the
workspace rather than on your personal plan.
## Related
* [Plans and limits](/help/plans-and-limits)
* [Managing your subscription](/help/account/manage-your-subscription)
* [Invoices and receipts](/help/account/invoices-and-receipts)
# Deleting your account
Source: https://docs.openwhispr.com/help/account/delete-your-account
How to permanently delete your account and all your data, and what happens to your subscription.
You can delete your account yourself, from inside the app, and it takes effect
immediately.
Open **Settings**, choose **Account** under **Account**, and scroll to **Delete
Account**. Click **Delete My Account**, then confirm by typing
**Delete Everything**.
This cannot be undone. There is no grace period and no recovery — once it runs,
your data is gone from our side and from your machine.
## What gets deleted
* Your OpenWhispr account
* All cloud-synced notes
* All local data on this machine — transcriptions, audio recordings, downloaded
models, calendar connections and settings
## What happens to your subscription
If you have an active subscription, **deleting your account cancels it for you**.
You don't need to cancel first, and you won't be charged again.
If you want your money back as well, ask us for that **before** you delete —
once the account is gone we have far less to work from. See
[Refunds](/help/account/refunds).
## If you own a team workspace
The app will stop you, with a message saying so. A workspace can't be left
without an owner, so before you can delete your account you need to either hand
the workspace over to someone else or delete the workspace itself. Email us if
you're not sure which you want — we'll walk you through it.
## Just want to stop paying?
Deleting is the heavy option and people sometimes reach for it when they meant
something lighter:
* **Stop being charged, keep everything** →
[cancel your subscription](/help/account/cancel-your-subscription). Local
dictation keeps working, unlimited, on the Free plan.
* **Move to a different email address** →
[changing your email](/help/account/change-your-email), which keeps your notes
and your subscription.
## Data protection requests
If you're making a formal data request — erasure under GDPR, a copy of your
data, or anything your legal team has asked you to put in writing — email
[support@openwhispr.com](mailto:support@openwhispr.com) and say so explicitly. A
person handles those, and we'll confirm in writing what was done. Deleting the
account in-app achieves the erasure, but it doesn't give you the paper trail.
Our [Privacy Policy](https://openwhispr.com/privacy) sets out what we hold and
why.
## FAQ
No. Export anything you want to keep first — see
[Notes](/guides/notes).
No. Uninstalling removes the app from your machine; your account and any
cloud-synced notes stay. Use Delete Account if you want it all gone.
Tell us — that shouldn't happen and we'll stop it.
## Related
* [Cancelling your subscription](/help/account/cancel-your-subscription)
* [Changing your email address](/help/account/change-your-email)
* [Refunds](/help/account/refunds)
# Discounts and promo codes
Source: https://docs.openwhispr.com/help/account/discounts-and-promo-codes
Where to enter a promo code, and how to request the 40% student, education, military, non-profit or accessibility discount.
If you have a promo code, there's a box for it at checkout. Go to
**Settings → Plans & Billing** under **Account**, click **Manage Billing**,
and on the Stripe checkout page click **Add promotion code** before you pay.
## Student, education, military, non-profit and accessibility discounts
We offer **40% off for 12 months** in five categories. One policy, one way to
ask, whichever category fits you:
| Email subject line | Who it's for | Proof we accept |
| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Student Discount` | Students, in any programme | Student ID, enrollment letter, or transcript |
| `Education Discount` | Teachers, lecturers and academic staff | Faculty or staff ID |
| `Military Discount` | Active duty and veterans | Military ID, discharge papers (DD-214) or veteran ID — with sensitive details covered, if you prefer |
| `Non-profit Discount` | People working at a registered non-profit | Proof of the organisation's non-profit registration, or a LinkedIn profile |
| `Accessibility Discount` | People who rely on OpenWhispr as an assistive tool | A short note on how you use it — we won't ask for medical documentation |
### How to request one
Email [support@openwhispr.com](mailto:support@openwhispr.com) with:
1. The **subject line from the table, exactly as written** — it routes your
request straight to review.
2. Your **full name** and the **email on your OpenWhispr account**.
3. Your **proof attached**, per the table. Feel free to cover any sensitive
details (photos, ID numbers) — we only need to see your name and current
status.
We review requests within a few business days. If you're approved, we'll reply
with a discount code that is **single-use and personal to you** — it won't work
for anyone else. Enter it at checkout as described at the top of this page. If
you already have a subscription, say so in your email and we'll apply the
discount to it directly instead.
A few things worth knowing:
* **The discount runs for 12 months.** After that, your plan returns to the
standard price. If you're still eligible, email us again with current proof
and we'll issue you a fresh code.
* **You don't need a .edu email address.** Enrollment is what we check, not
your email domain — universities outside the US, online programmes and
bootcamps all qualify the same way.
* **Military covers both active duty and veterans.** One category, same
discount.
## Ways to pay less
**Pay annually.** The straightforward one, and it needs no code. Pro is \$8/month
or \$80/year, and Business is \$16/user/month or \$160/user/year — a year up front
costs you ten months rather than twelve. You can switch an existing monthly
subscription to annual at any time; see
[Changing your plan](/help/account/change-your-plan).
**Refer people.** Every friend who signs up through your link and uses
OpenWhispr earns you a free month, with no cap on how many. See
[Referrals](/help/account/referrals).
**Use local models.** Not a discount so much as the alternative to needing one:
on-device transcription is unlimited on every plan including Free, and costs
nothing. If the reason you're upgrading is the cloud word allowance, a local
model may remove the need entirely — see
[Cloud vs local processing](/guides/cloud-vs-local).
## FAQ
The box is on the Stripe checkout page, but you get there from inside
OpenWhispr:
1. In the OpenWhispr app, open **Settings**.
2. Choose **Plans & Billing** under **Account**.
3. Click **Manage Billing** — this takes you to Stripe, which handles
our payments.
4. On the Stripe page, click **Add promotion code**, just above the
total, and enter your code before you pay.
If your code isn't being accepted, send it to us and we'll check whether
it's expired.
Yes, send us an email and we'll apply it to your existing subscription.
If you hold a university ID, that's the Education discount. If you don't,
email us anyway and tell us a bit about your situation — we read every
request.
Not at the moment. The reliable saving is annual billing, which is
always available.
## Related
* [Changing your plan](/help/account/change-your-plan)
* [Referrals](/help/account/referrals)
* [Plans and limits](/help/plans-and-limits)
# Invoices and receipts
Source: https://docs.openwhispr.com/help/account/invoices-and-receipts
Where to download your invoices, and how to get a company name or VAT number onto them.
Your invoices live on your billing page at Stripe. Open **Settings**, choose
**Plans & Billing** under **Account**, click **Manage Billing**, and you'll find
your full payment history there with a downloadable PDF for each one.
Stripe also emails a receipt every time you're charged, to the address on your
account.
## Getting your company details on the invoice
If you're expensing OpenWhispr or claiming the VAT back, the invoice usually
needs a company name, an address, and a tax or VAT number on it.
**Email [support@openwhispr.com](mailto:support@openwhispr.com)** with the
details you need on it and we'll reissue the invoice. We don't collect tax
numbers at checkout today, so this is a manual step at our end rather than
something you can set yourself — we'd rather tell you that than have you hunt
for a field that isn't there.
Send us:
* The company name and billing address as they should appear
* Your VAT or tax registration number, if you need one shown
* Which invoice (the date, or the amount)
## FAQ
They're all in your billing history at Stripe, however far back they go. If
you can't get in — for example the card holder has left the company — email
us and we'll send them over.
Receipts go to the address on your account. To change that address, see
[Changing your email address](/help/account/change-your-email).
What you pay is the price shown at checkout. If you need the tax position
stated formally for your finance team, email us and we'll put it in writing.
On Enterprise, yes — email us and we'll set it up. On Pro and Business,
payment is by card through Stripe.
## Related
* [Managing your subscription](/help/account/manage-your-subscription)
* [Changing your plan](/help/account/change-your-plan)
* [Refunds](/help/account/refunds)
# Is OpenWhispr free?
Source: https://docs.openwhispr.com/help/account/is-openwhispr-free
What the Free plan actually gives you, what it doesn't, and whether you need to pay.
Yes, and it stays free — the Free plan isn't a trial and it doesn't expire. No
card is needed to start.
What's worth understanding is that OpenWhispr has two ways of turning speech
into text, and only one of them has a limit on the free plan.
## Free, with no limit at all
**Dictation using a local model runs entirely on your own machine.** It doesn't
touch our servers, so there's nothing for us to meter. It's unlimited on the
Free plan — unlimited words, no file size cap, and it works offline. It's also
the most private option, because your audio never leaves your computer.
The same goes for **using your own API key** (BYOK) with a provider like OpenAI:
you're paying them directly, so we don't limit it on any plan.
## Free, with a weekly allowance
**OpenWhispr Cloud** is our hosted transcription, which we pay for. On the Free
plan you get **2,000 words per rolling 7 days**.
Rolling means there's no Monday reset — each transcription simply stops counting
once it's more than seven days old. If you used your allowance last Tuesday, it
frees up again this Tuesday.
There's also a **25 MB limit on files you upload** to OpenWhispr Cloud on the
Free plan. A 45-minute recording is usually 40–65 MB, so long files need either
a paid plan or a local model — which has no size limit at all. This one catches
people out, so it's worth knowing before you record something long.
## So do you need to pay?
Honestly: a lot of people don't.
* **If you dictate with a local model**, the Free plan is the whole product, and
paying gets you very little you'd notice.
* **If you want cloud transcription regularly**, 2,000 words a week is roughly
15 minutes of speech, and Pro at \$8/month removes the limit.
* **If you upload long recordings**, the 25 MB cap is the thing that will push
you to either a paid plan or a local model.
The full breakdown is in [Plans and limits](/help/plans-and-limits).
## FAQ
Only through a referral — if you sign up via someone's invite link, your
first 30 days of Pro are free. See [Referrals](/help/account/referrals).
Everyone else starts on the Free plan, which doesn't run out.
No. You only enter payment details if you choose to upgrade.
Cloud transcription pauses until some of your usage ages past seven days.
Local dictation carries on working the whole time — it isn't affected.
No. Transcription quality depends on the model you choose, not on your plan.
## Related
* [Plans and limits](/help/plans-and-limits)
* [Cloud vs local processing](/guides/cloud-vs-local)
* [Changing your plan](/help/account/change-your-plan)
# Managing your subscription
Source: https://docs.openwhispr.com/help/account/manage-your-subscription
Where your plan, billing date and payment details live, and what you can change yourself.
Everything to do with your plan lives in one place: open **Settings**, then
choose **Plans & Billing** under **Account**. The **Plan** section at the top
shows the plan you're on and, if you're paying, the date of your next bill.
From there, **Manage Billing** opens your billing page at Stripe, who handle
payments for us. That's where you update your card, download invoices, change
your plan or cancel.
## What you can do yourself
Upgrade, downgrade, or switch between monthly and annual billing.
Stop future payments. Local dictation keeps working.
Change the payment method on file, or fix a failed payment.
Download receipts and past invoices.
## What the Plan section shows you
The button under your plan changes depending on where you stand, which is worth
knowing so you're not hunting for one that isn't there:
| If you're | The button says | What it does |
| ------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| Paying for OpenWhispr yourself | **Manage Billing** | Opens your Stripe billing page |
| On the Free plan | **Upgrade** | Starts checkout |
| On a free month from a referral | **Upgrade** | Starts a paid subscription — see [Referrals](/help/account/referrals) |
| Behind on a payment | **Update Payment Method** | Opens Stripe to fix the card |
If your OpenWhispr is paid for by your team rather than by you, this section
tells you so instead, and names who manages the billing. There's nothing for you
to change — ask whoever owns the workspace.
## Where to find your usage
The same **Plans & Billing** section shows how much of your allowance you've
used this week if you're on the Free plan — the words counter and the
`words this week` line underneath it. What that allowance actually is, and the
limits that apply on each plan, are in
[Plans and limits](/help/plans-and-limits).
## FAQ
No. The Free plan is free forever and doesn't ask for payment details. You
only add a card if you decide to upgrade.
Payments are handled by Stripe, so card details and invoices live with them
rather than with us. It also means we never store your card number.
Not from inside the app yet — email us and we'll move it for you. See
[Changing your email address](/help/account/change-your-email).
## Related
* [Plans and limits](/help/plans-and-limits)
* [Changing your plan](/help/account/change-your-plan)
* [Cancelling your subscription](/help/account/cancel-your-subscription)
# A payment failed
Source: https://docs.openwhispr.com/help/account/payment-failed
What happens when a card is declined, what you keep in the meantime, and how to fix it.
Nothing dramatic happens. Your account stays exactly where it is — we move you
to the Free plan's allowance until the payment goes through, and everything
comes back the moment it does.
The app tells you with a banner reading **"We couldn't process your payment"**,
and the button under it takes you where you need to go.
## Fixing it
In **Settings**, choose **Plans & Billing** under **Account**.
While a payment is outstanding, the button in the **Plan** section reads
**Update Payment Method** rather than Manage Billing.
That opens your billing page at Stripe. Add or update the card there.
Stripe retries the outstanding payment automatically once there's a card that
works. You don't need to do anything else, and you don't need to resubscribe.
## What you keep in the meantime
* **Local dictation and your own API keys** — unlimited, exactly as before.
These never depended on the payment.
* **OpenWhispr Cloud** — the Free allowance of 2,000 words per rolling 7 days.
* **All your notes and transcriptions** — untouched. Nothing is deleted over a
failed payment.
## Why cards get declined
The common ones, in roughly the order we see them:
* The card expired.
* The bank blocked it as an unexpected international or online charge — a
surprising share of these, and usually fixed by approving it in your banking
app and retrying.
* Insufficient funds at the moment the charge ran.
* The card was replaced after fraud and the old number is still on file.
## FAQ
The subscription eventually ends if the payment never succeeds. Your account
and data stay, and you can subscribe again whenever you want.
It clears once Stripe confirms the retry. If it's still there after a few
minutes, close and reopen Settings — and tell us if it persists.
Email us with the dates and we'll refund the duplicate. See
[Refunds](/help/account/refunds).
## Related
* [Managing your subscription](/help/account/manage-your-subscription)
* [Invoices and receipts](/help/account/invoices-and-receipts)
* [Refunds](/help/account/refunds)
# Referrals — give a month, get a month
Source: https://docs.openwhispr.com/help/account/referrals
How the referral programme works, when the free month actually lands, and how to track invites.
Invite someone to OpenWhispr and you both get a free month of Pro. Open the app
and click **Get a free month** in the sidebar — that opens your invite link,
which you can copy and share, or send straight to an email address from the same
screen.
## How it works
Everyone gets a personal invite link. Copy it from **Get a free month**, or
enter your friend's email and we'll send the invite for you.
They need to sign up using your link for the referral to be attached to their
account.
A referred account gets its **first 30 days of Pro free** at the point they
start a subscription. No card charge until the 30 days are up.
Your free month lands when they've actually dictated **2,000 words** through
OpenWhispr Cloud — not the moment they sign up. We'll email you when it does.
The 2,000-word threshold is there so the reward reflects someone genuinely
trying the product rather than an empty signup. It's the same 2,000 words as the
Free plan's weekly allowance, so a referred friend typically crosses it within
their first week of real use.
## Tracking your invites
The **Get a free month** screen has a **Past invites** tab showing who you've
invited and where each one stands — **Opened**, then **Converted** once they
qualify. It also totals your **Months earned**.
## What your free month does
* **If you're already paying**, your next billing date moves back by a month —
you're not charged during it.
* **If you're on the Free plan**, you get a month of Pro. When it ends you go
back to Free, with nothing to cancel and no card required.
Refer more than one person and the months stack.
## FAQ
The reward triggers once they've dictated 2,000 words through OpenWhispr
Cloud. Words transcribed with a local model or their own API key don't count
toward it, because those never reach us. If they're well past that and
nothing's arrived, email us — we can look it up.
No.
No — the link has to be how they first sign up. Once an account exists, it
can't be attributed retroactively.
It's the only free trial OpenWhispr has. Everyone else starts on the Free
plan, which is free forever rather than time-limited — see
[Plans and limits](/help/plans-and-limits).
## Related
* [Plans and limits](/help/plans-and-limits)
* [Managing your subscription](/help/account/manage-your-subscription)
* [Discounts and promo codes](/help/account/discounts-and-promo-codes)
# Refunds
Source: https://docs.openwhispr.com/help/account/refunds
How to ask for a refund, what we can usually do, and how long it takes to arrive.
Email [support@openwhispr.com](mailto:support@openwhispr.com) from the address
on your account and tell us you'd like a refund. You don't need a reason,
though if something went wrong we'd like to hear it — that's usually how we find
out about the problem.
A person reads every one of these. We're a small team and we'd rather give you
your money back than have you feel stuck with something you're not using.
## What to expect
* **Monthly plans** — we can normally refund your most recent payment straight
away.
* **Annual plans** — we look at these individually, and we'll come back to you
rather than leaving you waiting. Tell us roughly when you stopped using it and
we'll work something out.
* **Refunds go back to the card you paid with.** Stripe handles the transfer;
banks typically take 5–10 working days to show it, which is outside our
control.
Asking for a refund doesn't automatically cancel your subscription, and
cancelling doesn't automatically refund you — they're two separate things. If
you want both, say so in the same email and we'll do both.
## Before you ask
If the reason is that something isn't working, it's worth one message first.
Plenty of refund requests we get turn out to be a microphone permission, a
hotkey conflict, or a limit nobody told you about — all of which we can fix in a
reply. If we can't, we'll refund you and that's the end of it.
## FAQ
We process it when we reply to you. After that it's your bank's timeline —
usually 5–10 working days for the money to appear on your statement.
Tell us and we'll refund it. That shouldn't happen, and if it did we want to
know why.
Email us before contacting your bank and we'll find it — charges appear
under the name on your receipt, which isn't always the one you expect. If
it's genuinely not you, we'll refund it and shut the subscription down.
Ask. If you've just been billed for a period you haven't used, that's
normally straightforward.
## Related
* [Cancelling your subscription](/help/account/cancel-your-subscription)
* [Invoices and receipts](/help/account/invoices-and-receipts)
* [Getting help](/help/getting-help)
# Seats — adding, removing and what counts
Source: https://docs.openwhispr.com/help/account/seats
What uses up a seat, how to buy more, and how seats come back when people leave.
A workspace buys a number of seats, and each person who can use OpenWhispr
through the workspace holds one. **Settings → Workspace** under **Account**
shows where you stand, on the Members tab: *"4 of 5 seats used."*
## What consumes a seat
* **Every member.** Owner, admin or member — by default they all hold a seat.
* **Every invitation you've sent that hasn't been accepted yet.** This is the one
that surprises people. A pending invite reserves its seat so the person has
somewhere to land when they accept. Revoke it, or let it expire, and the seat
comes back.
**Admins can be given access without a seat.** When you invite someone as an
admin, you can mark them as admin-only, and they'll manage the workspace without
consuming paid capacity — useful for an IT or ops person who administers
OpenWhispr but doesn't dictate. This is available for the admin role only;
regular members always hold a seat.
## Adding seats
If you're out of capacity, inviting someone fails with a message telling you to
add seats first. To add them: open the workspace billing card in **Settings →
Workspace**, and use **Add seat**.
Before it goes through, OpenWhispr shows you the new capacity and the exact
**Charge today** — the change is prorated, so you pay for the rest of the
current period rather than a full month.
A workspace can hold up to **500 seats**. If you need more than that, talk to us
about Enterprise.
## Removing seats
**Seats are released automatically.** Remove a member, revoke a pending
invitation, or have someone leave the workspace, and the workspace's seat count
drops to match — you stop paying for capacity you're not using, without having
to remember to adjust anything.
Because of that there's no "remove a seat" button: seats follow the people. What
you can't do is set the number *below* the seats currently in use — free up the
seat first by removing the person, and the count follows.
## FAQ
It updates once Stripe confirms. If it's still wrong after a few minutes,
tell us — that's a bug worth knowing about.
Pending invitations hold their seat. Revoke any invites that aren't going to
be accepted and the capacity comes straight back.
The unused portion becomes credit on the workspace's account and comes off
the next invoice, rather than going back to the card.
Yes. Seats are per workspace, and each workspace bills for its own.
## Related
* [Billing for a team](/help/account/workspace-billing)
* [Why can't I manage billing?](/help/account/who-pays-for-my-plan)
* [Transferring or deleting a workspace](/help/account/transfer-or-delete-a-workspace)
# Transferring or deleting a workspace
Source: https://docs.openwhispr.com/help/account/transfer-or-delete-a-workspace
Handing a workspace to someone else, closing one down, and what happens to the subscription.
Both live in **Settings** → **Workspace** under **Account**, on the **General**
tab. Both are owner-only.
## Transferring ownership
Use **Transfer ownership** on the Members tab and pick the person taking over.
They become the owner and inherit the billing; you stay in the workspace as an
admin.
Do this **before** the current owner's account goes away — someone leaving the
company, or deleting their OpenWhispr account. A workspace can't be left without
an owner, so the app will block an account deletion that would orphan one. If
you've hit that message, transferring is the way out of it.
## Leaving a workspace
If you're not the owner, **Leave workspace** removes you from it. You lose
access to its shared notes immediately, an admin can invite you back later, and
the seat you were holding is released.
## Deleting a workspace
Deleting a workspace **cancels its subscription and permanently removes all
shared notes, folders and integrations**. It cannot be undone.
**Delete workspace** is at the bottom of the General tab, and you confirm by
name. Everyone loses access to the shared content, and billing stops.
Notes that individual people created outside the workspace's shared spaces
belong to those people and aren't affected.
## Which one do you want?
* **Someone's leaving, the team carries on** → transfer ownership.
* **You're leaving, the team carries on** → leave the workspace.
* **The team is winding down and you want billing stopped** → delete the
workspace, or just cancel its subscription from the billing page if you want
to keep the content.
* **You want your own account and data gone** →
[delete your account](/help/account/delete-your-account) — but hand over or
delete any workspace you own first.
## FAQ
That's the block described above. Transfer the workspace to someone else, or
delete the workspace, and the account deletion will go through.
It cancels the subscription. If you'd like the unused part back, ask us —
see [Refunds](/help/account/refunds).
Email us from a company address and we'll help you sort out ownership.
## Related
* [Billing for a team](/help/account/workspace-billing)
* [Deleting your account](/help/account/delete-your-account)
* [Seats — adding, removing and what counts](/help/account/seats)
# Why can't I manage billing?
Source: https://docs.openwhispr.com/help/account/who-pays-for-my-plan
What it means when your plan is managed by someone else, and what you can still change yourself.
If **Plans & Billing** shows your personal plan as **Free** while you clearly
have paid features, your access is coming from a workspace seat rather than from
a subscription of your own. The screen names whoever manages the billing.
That's working as intended — someone at your organisation is paying for a
workspace, and you hold a seat in it. There's no subscription in your name, so
there's nothing for you to manage or cancel.
## What you can still do
* **Everything about how you use OpenWhispr** — models, hotkeys, languages,
dictionary, privacy settings. None of that is billing.
* **Buy your own subscription anyway**, if you want paid features that continue
after you leave the organisation. The two are independent.
* **Leave the workspace**, from **Settings → Workspace** under **Account**. You
lose access to its shared notes, and the seat is released.
## What you'll need to ask the owner for
* Changing the workspace's plan, or its card and invoices
* Adding seats so you can invite someone
* Removing members, or transferring ownership
## If your seat goes away
If the workspace subscription ends, or your seat is removed, your account
doesn't disappear — you drop to the Free plan. Local dictation stays unlimited,
your own API keys keep working, and OpenWhispr Cloud returns to 2,000 words per
rolling 7 days. Notes you created personally stay with you; notes that lived in
the workspace's shared spaces stay with the workspace.
## FAQ
Billing is restricted to the workspace **owner** — admins manage people and
spaces, not the card. If the owner has left, ownership can be transferred:
see [Transferring or deleting a workspace](/help/account/transfer-or-delete-a-workspace).
You're paying twice for the same thing. Cancel whichever you don't need —
usually the personal one. See
[Cancelling your subscription](/help/account/cancel-your-subscription).
Only the owner can. Ask them, or ask us and we'll send them to whoever owns
the account.
## Related
* [Billing for a team](/help/account/workspace-billing)
* [Seats — adding, removing and what counts](/help/account/seats)
* [Managing your subscription](/help/account/manage-your-subscription)
# Billing for a team
Source: https://docs.openwhispr.com/help/account/workspace-billing
How a workspace pays for OpenWhispr, who can change it, and how it relates to your personal plan.
A workspace has its own plan and its own bill, separate from anyone's personal
subscription. One person — the workspace **owner** — pays for it, and everyone
with a seat gets the paid features through that.
Open **Settings** and choose **Workspace** under **Account** to see it.
## Personal plan vs workspace plan
These are two different things and it's worth being clear which one you're
looking at.
| | Personal plan | Workspace plan |
| ------------------- | ------------------- | ----------------------- |
| Who pays | You | The workspace owner |
| Where you manage it | **Plans & Billing** | **Workspace** |
| What it covers | Just you | Everyone holding a seat |
| Priced | Per person | Per seat |
**You only need one of them.** If your workspace gives you a paid seat, your
personal plan can sit on Free and you still get the paid features — the
**Plans & Billing** section will say so, showing your personal plan as Free with
your paid access provided by the workspace.
## Starting a workspace subscription
New workspaces begin on the Free plan. Team spaces and shared notes need a paid
workspace plan, so the first thing an owner does is start one:
**Settings** → **Workspace** under **Account**.
Choose **Start subscription** and pick how many seats you need. The button
tells you what you're buying — *Start Business with 5 seats*, for example.
Checkout opens at Stripe. Business is \$20/user/month or \$200/user/year.
Afterwards, **Manage in Stripe** on the same screen opens the workspace's
billing page — card, invoices and cancellation, exactly like a personal
subscription but owned by the workspace.
## Only the owner can change it
Admins can manage members, roles and team spaces. **Billing is owner-only** — if
you're an admin rather than the owner, the workspace billing card tells you so
and there's nothing to click. That's deliberate: one payer, one card, no
surprises for whoever's name is on it.
## FAQ
Possibly — the two subscriptions are independent, so nothing cancels your
personal one automatically. If your workspace seat covers what you need,
[cancel the personal subscription](/help/account/cancel-your-subscription).
If you've just been double-billed for a period, ask us and we'll refund it.
Yes — \$200/user/year rather than \$20/user/month. Choose annual at checkout,
or switch later from the workspace's billing page.
Ownership can be transferred to another member — see
[Transferring or deleting a workspace](/help/account/transfer-or-delete-a-workspace).
Do it before their account goes away.
## Related
* [Seats — adding, removing and what counts](/help/account/seats)
* [Why can't I manage billing?](/help/account/who-pays-for-my-plan)
* [Plans and limits](/help/plans-and-limits)
# Your agent's name
Source: https://docs.openwhispr.com/help/agent/agent-name
Saying your agent's name during dictation hands the rest over to the agent. How that's detected, and how to rename or switch it off.
Your voice agent has a name, and saying it at the start of a dictation is one of
the two ways to reach the agent. The app puts it plainly: *"When you say 'Hey
\[name]' followed by an instruction, the AI executes your command — composing
content, formatting text, or answering questions — instead of transcribing it
verbatim."*
The name is removed from what gets typed, so you don't see it in the output.
## The default is "OpenWhispr"
Out of the box your agent is called **OpenWhispr**, and the feature is **on**.
That combination is worth knowing about, because "OpenWhispr" is a word you
might genuinely dictate — telling a colleague what you use, writing a review,
describing your setup. If a dictation *starts* with it, it goes to the agent.
If you use the agent, rename it to something you would never say by accident —
the app suggests names like Jarvis, Nova, or Atlas. If you don't use it,
switch it off. Either one removes the surprise.
## When the name counts as addressing it
Not every mention triggers the agent. The name only counts when it's genuinely
being addressed, which means one of:
* It's the **first thing** in the dictation.
* It **follows a greeting** — *hey*, *hi*, *hello*, *ok*, *okay*, *yo*, or
*please*.
* It **starts a new sentence**, after a full stop, question mark, or exclamation
mark.
A mention anywhere else is treated as ordinary text. Dictating *"I showed
OpenWhispr to a friend"* types that sentence — the name is in the middle, so
it's content, not a command.
## Near-misses count too
Speech-to-text doesn't always hear a name cleanly, so matching is deliberately
forgiving — it allows for a small number of wrong letters, and for the name
being split into two words. A name like "OpenWhispr" will also match things like
*"open whisper"*.
Longer names get slightly more tolerance than short ones. Names of one character
are ignored entirely.
The trade-off is intentional: it means the agent answers when you address it
slightly imprecisely, at the cost of occasionally triggering on something close.
## Changing the name
1. Open **Settings**, choose **Language Models** under **AI Models**, then the
**Voice Agent** tab.
2. Type a new name in **Agent Name**.
3. Click **Save**.
You'll get a confirmation telling you the new name and how to address it. Pick
something *"short and natural to say aloud"* — the app's own advice, and good
advice, since you have to say it out loud mid-sentence.
Renaming also adds the new name to your custom dictionary, so it's transcribed
reliably.
## Switching it off
On the same tab, turn off **Enable voice agent**. That stops the name trigger
completely — dictation is then always transcribed.
Switching it off here also disables the agent reached by the **Voice Agent
Hotkey**, since they're the same feature. If you want to keep the hotkey and
only lose the name trigger, rename the agent to something you'd never say
instead of turning it off.
## Related
* [The four things your voice can start](/help/agent/voice-modes)
* [The voice agent](/help/agent/voice-agent)
* [It answers me instead of typing](/help/fix/it-answers-instead-of-typing)
* [Custom dictionary](/help/customise/custom-dictionary)
# The chat agent
Source: https://docs.openwhispr.com/help/agent/chat-agent
A chat window you can talk to, which can search your notes, create and edit them, search the web, and check your calendar.
The chat agent is a conversation rather than a one-shot instruction. It opens in
an overlay above whatever you're working in, keeps its history, and can act on
your notes.
Unlike the voice agent, it doesn't type into the app you're using — the
conversation stays in its own window.
## Opening it
Set the **Chat Agent Hotkey** under **Settings** → **Hotkeys** under **App**.
The same key opens and closes the overlay.
Inside, you can type, or hold the input's speak control to talk. The placeholder
tells you which key to press.
## What it can do
The agent has tools it can use on your behalf, and it tells you which one it's
running as it goes — *"Searching notes…"*, *"Creating note…"*, and so on.
| Tool | What it does | Available |
| --------------------- | ----------------------------------------------- | ------------------------- |
| **Search notes** | Finds relevant notes | Always |
| **Read note** | Opens one note in full | Always |
| **Create note** | Writes a new note | Always |
| **Update note** | Edits an existing note | Always |
| **List folders** | Reads your folders, so it files things sensibly | Always |
| **Copy to clipboard** | Puts text on your clipboard | Always |
| **Web search** | Searches the web | Signed in |
| **Calendar** | Reads your upcoming events | Google Calendar connected |
Two of those are conditional. **Web search** needs you signed in to an
OpenWhispr account. **Calendar** appears only once you've connected Google
Calendar — without it the agent has no view of your schedule and will say so.
Note search runs against your synced notes when you're signed in with cloud
backup on, and against the notes on your device otherwise. Either way it
searches your own notes only.
## Conversations
Conversations are saved and you can pick one back up. **New** starts a fresh
one, which is worth doing when you change subject — a long conversation carries
its earlier context into every answer.
Any reply can be copied out with **Copy to clipboard**.
## Choosing a model
Set it under **Settings** → **Language Models** under **AI Models**, on the
**Chat** tab. It's independent of the voice agent's model, so you can run a
larger model for conversation and a faster one for quick voice instructions.
**System Prompt** on the same tab sets custom standing instructions for the chat
agent.
## Chat vs the voice agent
| | Chat agent | Voice agent |
| ------------- | ------------------------------------------------- | ---------------------------------- |
| Opens | An overlay window | Nothing — types at your cursor |
| Keeps history | Yes | No, each instruction stands alone |
| Can use tools | Yes | No |
| Best for | Working with your notes, research, back-and-forth | One-off instructions while writing |
## Related
* [The voice agent](/help/agent/voice-agent)
* [The four things your voice can start](/help/agent/voice-modes)
* [Notes](/guides/notes)
# The voice agent
Source: https://docs.openwhispr.com/help/agent/voice-agent
Press a key, say what you want done, and the result is typed at your cursor instead of your words.
The voice agent turns speech into an **instruction** rather than text. Press its
hotkey, say what you want, and what appears at your cursor is the result — a
drafted email, a rewritten paragraph, an answer.
The app sums it up as *"Speak a request — your AI agent types the result, not
your words."*
## Setting it up
**1. Give it a hotkey.** Open **Settings**, then **Hotkeys** under **App**, and
set the **Voice Agent Hotkey**. It's empty by default, so until you set one the
only way to reach the agent is by [saying its name](/help/agent/agent-name).
**2. Check it's enabled.** Open **Settings**, choose **Language Models** under
**AI Models**, then the **Voice Agent** tab. **Enable voice agent** is on by
default.
## Using it
Press the hotkey and speak. You don't need to say the agent's name first — the
hotkey already means "this is an instruction". The app's examples:
* *"Translate to Italian: I talk faster than I type"*
* *"Write a short email to my boss telling him I want a promotion, his name is
Mark"*
* *"What is 5 × 5?"*
The result is typed wherever your cursor is, exactly like dictation — you can
use it inside an email, a document, a chat box.
## Editing text you've already written
Select some text first, then press the hotkey and say what you want changed —
*"make this more formal"*, *"turn this into bullet points"*, *"fix the typos"*.
The agent rewrites **the selection in place** instead of adding something new
below it.
With nothing selected, the same hotkey behaves as described above: the result
is inserted at your cursor.
## Sharing your screen as context
The agent can also look at what's on your screen, so a command can refer to
what you're looking at — *"reply to this email"*, *"explain the error on
screen"*, *"summarize this page"*.
This is **off by default**. To turn it on, open **Settings**, choose
**Language Models** under **AI Models**, then the **Voice Agent** tab, and
enable **Share screen context**. On macOS you'll be asked for **Screen
Recording** permission the first time.
When it's on, pressing the voice agent hotkey captures the display your cursor
is on and sends that image with your command. A few things worth knowing:
* The screenshot is used for that one request only. It's never saved to disk,
never added to your notes or history, and never written to logs.
* The dictation panel itself is excluded from the capture.
* Only the voice agent hotkey captures. Ordinary dictation and saying your
agent's name never do.
* Not every model can read images. If yours can't, the command still runs —
just without the screenshot.
**Using a different model for screenshots.** Some people want a cheap, fast
model for everyday commands and a stronger one when an image is involved. Turn
on **Separate vision model** underneath and pick that second model; it's used
only for commands that carry a screenshot.
Screen context isn't available on Linux under Wayland, which doesn't allow an
app to capture the screen without a system prompt each time. The toggle is
disabled there and the agent works normally without it.
## Choosing where it runs
On the **Voice Agent** tab you choose the model, independently of the ones used
for transcription and cleanup:
| Mode | What it means |
| ---------------------- | ---------------------------------------------------- |
| **OpenWhispr Cloud** | Managed for you, no API key needed |
| **Bring your own key** | OpenAI, Anthropic, Gemini, or Groq with your own key |
| **Local** | An on-device model — fully private |
| **Self-hosted** | Your own OpenAI-compatible endpoint |
| **Enterprise** | AWS Bedrock, Azure OpenAI, or Google Vertex |
Cloud and self-hosted modes work without naming a model. The others need one
chosen explicitly, and the agent won't run until you do.
## Its instructions
**Agent prompt**, on the same tab, is the system prompt used when the agent
runs. Leave it empty and a built-in default is used. Set it if you want a
consistent tone or format across everything the agent writes.
## If nothing happens
If the agent can't run — no model chosen in a mode that needs one, or it's
switched off — a dictation started with the voice agent hotkey comes back as
**the plain transcript**, with no cleanup applied. So getting your own raw words
back from that shortcut is the signal that the agent isn't reachable, rather
than that it misunderstood you.
Check, in order: **Enable voice agent** is on, and a model is selected if your
mode requires one.
If the agent was reachable but the request failed, you'll see an **Agent
Unavailable** notice alongside the raw transcript, so you can tell a genuine
failure apart from the agent not being set up.
And if you have screen context on but the screenshot couldn't be sent, you'll
see a **Screen Context Skipped** notice — the command still ran, just without
the image.
## Related
* [Your agent's name](/help/agent/agent-name)
* [The four things your voice can start](/help/agent/voice-modes)
* [The chat agent](/help/agent/chat-agent)
* [Your hotkeys](/help/dictation/hotkeys)
# The four things your voice can start
Source: https://docs.openwhispr.com/help/agent/voice-modes
Dictation, the voice agent, translation and meeting mode all listen to you but do different things. This is how to tell them apart.
Nearly every "OpenWhispr did something I didn't expect" turns out to be one of
four features running when you meant another. They all start from your voice,
and each has its own shortcut.
## The four
| What you want | What starts it | What you get |
| -------------------------- | -------------------------------------------------- | ------------------------------------ |
| Type what I say | **Dictation Hotkey** | Your words, tidied, at the cursor |
| Do what I say | **Voice Agent Hotkey**, or saying the agent's name | The *result* of your instruction |
| Say it in another language | **Translation Hotkey** | Your words, translated |
| Take notes on this meeting | **Meeting Mode Hotkey** | A recorded, transcribed meeting note |
There's a fifth shortcut, the **Chat Agent Hotkey**, but it's less confusable —
it opens a chat window rather than typing anywhere.
All five are set in one place: **Settings** → **Hotkeys** under **App**.
## Dictation vs the voice agent
This is the pair that causes trouble, because both put text at your cursor and
only one of them puts *your* text there.
**Dictation** transcribes. Say *"what time is the meeting tomorrow"* and those
six words are typed.
**The voice agent** executes. Say the same thing and it answers the question —
the app describes this shortcut as *"Speak a request — your AI agent types the
result, not your words."*
There are **two ways** to reach the agent, which is why turning off one doesn't
always stop it:
1. **Its hotkey.** Everything you say after pressing it is an instruction.
2. **Its name.** During ordinary dictation, starting with the agent's name
routes the whole thing to the agent instead.
The second one is the surprising one, and it's on by default. [Your agent's
name](/help/agent/agent-name) explains how it decides, and how to change or
switch it off.
## Dictation vs cleanup
A subtler case: you dictated, you got your own words back, but they're not
*exactly* the words you said — punctuation you didn't speak, filler words gone,
a clumsy sentence tidied.
That's **dictation cleanup**, which runs on your transcript by default. It's not
the agent, and it isn't meant to change your meaning. See [dictation
cleanup](/help/dictation/cleanup) for what it does and how to turn it off.
## Working out which one ran
Ask what came back:
* **Your words, roughly as spoken** — dictation, working normally.
* **Your words, tidier** — dictation with cleanup.
* **An answer, a rewrite, or something you didn't say** — the voice agent.
* **Another language** — translation.
* **Nothing at the cursor, a panel appeared** — meeting mode or the chat agent.
If it's the agent and you didn't want it, [it answers me instead of
typing](/help/fix/it-answers-instead-of-typing) is the fix-it walkthrough.
## Related
* [Your agent's name](/help/agent/agent-name)
* [The voice agent](/help/agent/voice-agent)
* [Your hotkeys](/help/dictation/hotkeys)
* [It answers me instead of typing](/help/fix/it-answers-instead-of-typing)
# Choose your microphone
Source: https://docs.openwhispr.com/help/customise/choose-your-microphone
Pick which input device OpenWhispr listens to, and why the built-in one is often the better choice.
By default OpenWhispr uses whatever microphone your operating system is using.
If that's the wrong one — or if you've plugged in something better — you can
choose explicitly.
## Choosing a device
Open **Settings**, then **Preferences** under **App**, and find
**Input Device**.
Pick a specific microphone from the list, or leave it on **System Default** to
follow whatever your operating system is set to. The app confirms the current
choice underneath — *"Using: …"* — and marks your machine's own microphone as
**(Built-in)**.
**System Default** follows your OS. That's convenient, but it means plugging
in headphones or joining a call can silently change which microphone
OpenWhispr hears. If dictation works and then mysteriously stops after you
connect something, this is the first place to look.
## Prefer Built-in Microphone
There's a separate setting called **Prefer Built-in Microphone**, and the app is
blunt about why: *"External microphones may cause latency or reduced
transcription quality."*
That reads backwards if you've bought a good microphone, so it's worth
explaining. The problem is usually not the microphone — it's the *link*.
Bluetooth headsets in particular switch to a low-quality, low-bandwidth mode
when they're being used as an input device, which is exactly what speech
recognition is worst at. Your laptop's built-in microphone, unglamorous as it
is, is a clean wired input at full bandwidth.
Rules of thumb:
| Setup | Recommendation |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| **Bluetooth headset** (AirPods and similar) | Prefer the built-in microphone. Use the headset for listening |
| **Wired USB or XLR microphone** | Use it — this is the case where an external device is genuinely better |
| **Wired earbuds with an inline mic** | Either. Try both and compare |
| **Laptop on its own** | Built-in, which is what you'll get anyway |
## If no microphones are listed
The app will say *"No microphones were detected"* and point you at your system
settings. That's an operating-system-level problem rather than an OpenWhispr
one — see [my microphone isn't working](/help/fix/microphone-not-working),
which covers permissions per platform.
If the list is populated but you get *"Unable to access microphone,"* it's a
permission rather than a device problem, and the same article covers it.
## Meetings use the same input
The microphone you choose here is the one used for dictation **and** for
recording your side of a meeting. Capturing the other participants is a separate
mechanism entirely — see
[capturing both sides of the call](/help/meetings/capture-both-sides).
## Related
* [My microphone isn't working](/help/fix/microphone-not-working)
* [Improve accuracy](/help/dictation/improve-accuracy)
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
# Teach OpenWhispr your words
Source: https://docs.openwhispr.com/help/customise/custom-dictionary
Add names, jargon and acronyms to the custom dictionary so they come out right every time.
If OpenWhispr keeps mangling a colleague's name, a product name or an acronym,
add it to your dictionary. Words in there are passed to the transcription model
as context, which makes it far likelier to pick them over a similar-sounding
everyday word.
## Adding words
Click **Dictionary** in the sidebar and stay on the **Dictionary** tab.
Type a word and press Enter. The placeholder shows the format:
*"Add words separated by commas — OpenWhispr, Supabase, John Snow, ARR"* — so
you can add several at once. Words take effect on your next transcription;
there's nothing to save.
To add a lot at once, use **Import a list** and paste them in, one per line or
comma-separated. OpenWhispr tells you how many it found — *"37 words ready"* —
before you commit.
There's an **Export dictionary** action too, which is the one to use before
moving to a new machine.
## What's worth adding
| Category | Examples |
| ------------------------- | ------------------------------------------- |
| Names it gets wrong | Sergey, Xanthe, Priya, Siobhán |
| Product and company names | OpenWhispr, Supabase, Kubernetes |
| Acronyms and initialisms | ARR, SOC 2, DPA, PII |
| Jargon in your field | amortisation, polymerase, arbitrage |
| Internal terms | project codenames, team names, system names |
Add the spelling you want to see. If you want "SOC 2" rather than "sock two",
that's the entry.
Don't paste your whole vocabulary in. The dictionary works as a hint to the
model, and a very long list dilutes it — the fifty words you actually get
wrong beat five hundred you don't.
## Auto-learn from corrections
OpenWhispr can watch for the moment you fix a transcription in the app you
dictated into, and add the corrected word for you.
The setting is **Auto-learn from corrections**, under **Settings** →
**Preferences** (in the **App** group).
It's a good way to build a dictionary without thinking about it — the words you
correct are by definition the ones being got wrong. If you'd rather OpenWhispr
didn't watch for corrections, leave it off.
## Editing and removing words
**Hover over a word in the list.** A pencil and a **✕** appear at the right of
that row — pencil to correct the spelling, **✕** to remove it.
Both controls are invisible until you hover, so the list looks read-only at
rest. The same is true of [snippets](/help/customise/snippets).
To empty the whole list, use **Clear all**. It asks first and can't be undone:
*"This will remove all words from your custom dictionary."*
Some entries are marked **Added by default** — those came with the app.
## When it doesn't help
The dictionary raises the odds; it isn't an override. If a word still comes out
wrong:
* Check you're not fighting the **language** setting — see
[languages](/help/dictation/languages).
* Try the **spelling you want to read**, not the phonetic one.
* For a phrase you say constantly, a [snippet](/help/customise/snippets) may
serve better — it replaces a trigger with exact text rather than nudging a
model.
* [Improve accuracy](/help/dictation/improve-accuracy) covers the rest.
## Related
* [Snippets](/help/customise/snippets)
* [Improve accuracy](/help/dictation/improve-accuracy)
* [Wrong words or wrong language](/help/fix/wrong-words-or-language)
# Where every setting lives
Source: https://docs.openwhispr.com/help/customise/settings-reference
A map of OpenWhispr's settings — the nine sections, what each one holds, and the tabs that hide things.
OpenWhispr's settings are grouped into nine sections. This page is the map, so
you can go straight to the one you want instead of hunting.
Open **Settings** from the sidebar.
## The nine sections
| Group | Section | Holds |
| ------------- | ------------------- | ---------------------------------------- |
| **Account** | **Account** | Profile and sign-in |
| **Account** | **Plans & Billing** | Plans, usage and billing |
| **Account** | **Workspace** | Members, team spaces and API keys |
| **App** | **Preferences** | Appearance, sounds and startup |
| **App** | **Hotkeys** | Dictation hotkey and activation |
| **AI Models** | **Speech-to-Text** | Engines for dictation and note recording |
| **AI Models** | **Language Models** | Models for chat, cleanup and summaries |
| **System** | **Privacy & Data** | Privacy, permissions and analytics |
| **System** | **System** | Updates, storage and developer tools |
## The two sections with tabs
These are where people most often look in the right section and still not find
the setting — because it's on a tab they didn't switch to.
**Speech-to-Text** has three tabs, and each keeps its **own** engine choice:
| Tab | Controls |
| ------------------ | ---------------------------------- |
| **Dictation** | The engine used when you dictate |
| **Note Recording** | The engine used for meetings |
| **Audio Upload** | The engine used for uploaded files |
Changing one changes only that one. "Switch to local" is not a single setting —
see [record a meeting](/help/meetings/record-a-meeting) for the meetings case
and [cloud vs local](/guides/cloud-vs-local) for the choice itself.
**Language Models** has five tabs: **Dictation Cleanup**, **Voice Agent**,
**Note Formatting**, **Chat** and **Translation** — again each with its own
model choice. The **Voice Agent** tab also holds
[**Share screen context**](/help/agent/voice-agent) (off by default) and, under
it, **Separate vision model** for routing screenshot-carrying commands
elsewhere.
## What's inside Preferences
**Preferences** is the longest section, and it renders in this order:
| Group | Holds |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| **Appearance** | **Theme** — Light, Dark or Auto |
| **Sound Effects** | **Dictation sounds**, **Pause media** |
| **Notifications** | Meeting detection, calendar reminders, app updates, and **Disable all notifications** |
| **Clipboard** | **Automatic pasting**, **Keep transcription in clipboard** |
| **Save notes as files** | The Markdown mirror, its location, and **Rebuild all files** |
| **Floating Icon** | **Auto-hide when idle**, **Start position** |
| **Language** | **Interface language**, **Transcription language** |
| **Startup** | **Launch at login** (macOS and Windows only), **Start minimized** |
| **Microphone** | **Input Device**, **Prefer Built-in Microphone** |
| **Auto-learn from corrections** | Learning from your edits |
[Running in the background](/platform/running-in-the-background) covers what
the appearance, sound, floating-icon and startup settings actually do.
## What's inside Privacy & Data and System
| Section | Also holds |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Privacy & Data** | **Usage analytics** (off by default), **Cloud backup** and its status lines, **Audio Retention** — including a **Disabled** option — and the **Permissions** block |
| **System** | **Updates** with **Current version**, **Debug Logging** and what gets logged, and **Data Management** — **Model cache** (Open, Clear cache) and **Reset app data** |
## Things that aren't where you'd guess
A short list of the ones that catch people out:
| Setting | Where it actually is |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Meeting Mode Hotkey** | **Hotkeys** — with the dictation, translation, voice agent and chat agent shortcuts |
| **Save notes as files** | **Preferences** |
| **Auto-learn from corrections** | **Preferences** |
| **Input Device** (microphone) | **Preferences** |
| **Meeting detection** and **Calendar reminders** notifications | **Preferences**, under **Notifications** |
| **Cloud backup** | **Privacy & Data** |
| **Audio Retention** and **Transcript Retention** | **Privacy & Data** |
| **Permissions** | A block *inside* **Privacy & Data**, not its own section |
| **Debug Logging** | **System** |
| **Current version** | **System**, under **Updates** |
| **Identify and label speakers** | **Speech-to-Text** → **Note Recording** tab, under the engine list — there is no "Meetings" section |
## Things that aren't in Settings at all
| What | Where |
| -------------------------------------------- | ------------------------------------------------------------------------------------ |
| Custom dictionary and snippets | **Dictionary** in the sidebar |
| Google Calendar, API keys, MCP, CLI | **Integrations** in the sidebar |
| Speaker identification for **one** recording | The pill on the meeting transcript itself — the global default is in Settings, above |
## Related
* [Choose your microphone](/help/customise/choose-your-microphone)
* [Teach OpenWhispr your words](/help/customise/custom-dictionary)
* [What we store, and for how long](/help/privacy/what-we-store-and-for-how-long)
* [Choosing a shortcut](/help/dictation/choosing-a-shortcut)
# Snippets: say a short phrase, get the full text
Source: https://docs.openwhispr.com/help/customise/snippets
Set up a trigger phrase that expands into a link, an intro, a sign-off or a prompt whenever you say it.
A snippet is a trigger phrase and the text it becomes. Say the trigger while
dictating and OpenWhispr swaps in the saved text — so you can say *"cal link"*
and get your full booking URL, correctly spelled, every time.
The app puts it well: *"the stuff you shouldn't have to say twice."*
## Creating one
Click **Dictionary** in the sidebar, then the **Snippets** tab.
In the field at the top — *"Add a trigger phrase"* — type the phrase you'll
say, like `cal link`. Then press **Enter** or click **Add**.
Triggers can be up to 80 characters, and you can't reuse one: if the trigger
already exists, **Add** stays greyed out and the app tells you *"A snippet
with this trigger already exists."*
A panel opens for the **Replacement** — the text the trigger becomes.
Choose **Create snippet**. It applies to your next dictation.
If you have no snippets yet you'll see a **New snippet** button instead of a
list. It doesn't open a form — it just puts your cursor in the trigger field,
so carry on from step 2.
## What people use them for
| Trigger | Replacement |
| ---------------- | ------------------------------------------------------------ |
| `My LinkedIn` | `linkedin.com/in/you` |
| `Sign off` | `Best, Alex · alex@example.com` |
| `Intro email` | `Hey, would love to find some time to chat later this week…` |
| `Rewrite prompt` | `Rewrite this to be more concise and professional` |
Anything you dictate repeatedly and get wrong repeatedly is a candidate: URLs,
email addresses, postal addresses, bank details, standard disclaimers, and
prompts you feed to an AI tool.
## How matching works
Worth knowing, because it explains both why snippets fire and why they don't:
* **Whole phrases only.** A trigger never matches inside a longer word, so a
trigger of `ask` won't fire on "asking" or "basket".
* **Case doesn't matter.** Say it however you say it.
* **The longest match wins.** If you have both `ask` and `investor ask`, saying
"investor ask" expands the longer one — so a specific trigger always beats a
general one that's contained in it.
* **Every occurrence expands**, not just the first.
* **Triggers must be unique.** A repeat is refused with *"A snippet with this
trigger already exists."*
## Choosing a good trigger
The replacement happens on your transcribed words, so the trigger has to be
something you'd say deliberately and never by accident.
* **Two words beat one.** `cal link` is safe; `link` will fire constantly.
* **Say it out loud first.** If it's a phrase you'd use in an ordinary sentence,
pick another.
* **Keep it easy to transcribe.** A trigger built from unusual words is one the
model may mishear — in which case the snippet won't fire because the trigger
never appeared in the text. If a trigger keeps failing this way, add its words
to your [dictionary](/help/customise/custom-dictionary).
## Editing and removing
**Hover over a snippet in the list.** A pencil and a **✕** appear at the right
of that row — pencil to edit the trigger or the replacement, **✕** to delete it.
Edits apply to your next dictation; there's nothing to reload.
The two controls are invisible until you hover, so a snippet row looks
read-only at rest. If you're hunting for a way to change one, that's where it
is.
## Snippets or dictionary?
They solve different problems and it's worth not mixing them up:
| Use a **snippet** | Use the **dictionary** |
| --------------------------------------------- | ---------------------------------------- |
| You want a short phrase to become longer text | You want a word transcribed correctly |
| The output is exact and unchanging | The output is whatever you actually said |
| `cal link` → your booking URL | "Siobhán" comes out as "Siobhán" |
A snippet is a substitution. A dictionary entry is a hint. If you want a
guarantee, use a snippet.
## Related
* [Teach OpenWhispr your words](/help/customise/custom-dictionary)
* [Improve accuracy](/help/dictation/improve-accuracy)
* [Cleanup and formatting](/help/dictation/cleanup)
# Where your text goes
Source: https://docs.openwhispr.com/help/dictation/auto-paste-and-clipboard
OpenWhispr pastes at your cursor when dictation finishes. What that needs, how to turn it off, and what happens on Wayland.
When dictation finishes, OpenWhispr types the text into whatever app your cursor
is in. You don't copy anything or switch windows.
Both controls for this live under **Settings** → **Preferences** under **App**,
in the **Clipboard** section.
## The two settings
**Automatic pasting** — *"Automatically paste transcribed text into the active
app when dictation finishes."* On by default. Turn it off if you'd rather paste
yourself, or if you're working in an app where an automatic paste lands in the
wrong place.
**Keep transcription in clipboard** — *"Keep dictated text in your clipboard so
you can paste it manually if needed."* Off by default. Worth turning on as a
safety net: with it on, even if the paste lands somewhere unexpected, the text
is still on your clipboard and `Cmd+V` / `Ctrl+V` gets it back.
## What automatic pasting needs
| Platform | Requirement |
| --------------- | ----------------------------------------------------------------------- |
| macOS | **Accessibility** permission |
| Windows | Nothing — works as installed |
| Linux (X11) | Included paste helper, falling back to `xdotool`, `wtype`, or `ydotool` |
| Linux (Wayland) | Not available — see below |
On macOS, grant Accessibility under **Settings** → **Privacy & Data** under
**System**, in the **Permissions** block. Each permission card has a **Grant
Access** button. Without it, OpenWhispr can transcribe but can't type into
another app.
## Wayland
On a Wayland session, automatic pasting isn't possible — the display protocol
deliberately doesn't let one app type into another. OpenWhispr tells you this
directly: *"Automatic pasting isn't available on this Wayland session.
OpenWhispr will copy text to your clipboard so you can paste manually with
Ctrl+V."*
Nothing is lost; it's one extra keystroke. If that matters to you, an X11
session restores automatic pasting.
## Media pausing
OpenWhispr can pause music while you dictate and resume when you're done. It's
**off by default** — turn on **Pause media** (*"Automatically pause music when
dictation starts"*) under **Settings** → **Preferences** under **App**, in the
sound effects group.
## If nothing arrives
If the text doesn't appear where you expected, or appears twice, those are
covered in detail:
* [My text isn't pasting](/help/fix/text-not-pasting)
* [My text pasted twice](/help/fix/text-pasted-twice)
## Related
* [How dictation works](/guides/dictation)
* [Dictating into other apps](/platform/dictating-into-other-apps)
* [My text isn't pasting](/help/fix/text-not-pasting)
* [Clipboard and audio on Linux](/help/fix/linux-clipboard-and-audio)
# Choosing a shortcut that works
Source: https://docs.openwhispr.com/help/dictation/choosing-a-shortcut
The rules a hotkey has to follow, which combinations your system won't give up, and what to use instead.
Most rejected shortcuts fail for one of three reasons: no modifier key, a
combination your operating system has already claimed, or another app got there
first. OpenWhispr tells you which when it refuses.
Set shortcuts under **Settings** → **Hotkeys** under **App**.
## The rules
The app shows these in a **Shortcut Guide** next to the hotkey field:
* **Use at least one modifier** — Ctrl, Alt, Shift, Cmd, or similar.
* **Three keys maximum.** Four-key combinations are rejected.
* **Single keys on their own aren't allowed.** The exception is the macOS Globe
key, which is handled separately.
* **Reserved system shortcuts are blocked.** Each platform has its own list.
* **Some combinations may still conflict** with whatever else you run — those
can't be predicted, only tried.
## The one principle worth knowing
**Pick a combination that types nothing.**
A hotkey is held down while you talk, sometimes for a minute, in whatever app
you're already typing into. If it ever slips through — a moment before the app
grabs it, a window that doesn't give it up — a combination ending in a letter
puts that letter in your document. A combination made only of modifier keys
can't.
That single test explains why the defaults are what they are, and it's a better
guide than any list.
## What to use
| Platform | Best | Also good |
| ----------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **macOS** | **Globe / Fn** — the default. One key, reachable with a thumb, types nothing. | `Control+Option` (modifiers only). Mouse button 4 or 5, if your mouse has them — macOS only. |
| **Windows** | **Ctrl+Win** — the default. Two modifiers, types nothing. | `Ctrl+Alt`, same reasoning. `Ctrl+Shift+K` if you'd rather have a letter. |
| **Linux** | **Ctrl+Super** — the default. | `Ctrl+Shift+K` or `Ctrl+Shift+J`. |
In every case **the default is the recommendation.** If dictation is working,
there's no reason to change it — the reasons to change are a physical conflict
with something you use constantly, a keyboard without the key, or wanting the
same shortcut across two machines with different layouts.
Modifier-only combinations like `Ctrl+Win` are fully supported and are what
the app ships with. You don't need a letter on the end.
## What to avoid
* **`Win+H` on Windows** — that's Windows' own voice typing shortcut. Binding it
puts two dictation systems on one key.
* **`Cmd+Space` on macOS** — Spotlight, and the default for several popular
launchers besides.
* **Anything ending in a common letter with one modifier** — `Ctrl+S`, `Cmd+F`
and their neighbours mean something in nearly every app, and most are blocked
outright.
* **Caps Lock.** Some dictation tools use it; OpenWhispr doesn't support it.
On **Linux**, three combinations shown in the app's own Shortcut Guide —
`Super+S`, `Ctrl+Alt+D` and `Alt+Space` — are on the reserved list and will be
refused when you try to set them. Use the table above instead. We're fixing
the in-app list.
## What the errors mean
| Message | What's happening |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| *"\[key] is already registered by another application"* | Something else on your machine claimed it first. Pick another, or quit the other app to find out which. |
| *"\[key] may be reserved by your desktop environment"* | Your OS or desktop won't release it. Nothing OpenWhispr can do — choose a different one. |
| *"Could not register \[key]. It may be in use by another application."* | Same as the first, where the system didn't say who has it. |
| *"Failed to update hotkey to \[key]. Check the format is valid."* | The combination isn't a shape the app accepts — usually a missing modifier. |
| *"This hotkey is already used for \[feature]"* | You've assigned it to another OpenWhispr shortcut. Each of the five needs its own. |
When a shortcut is rejected the app offers up to three alternatives inline.
They're a fixed per-platform list rather than a check of what's free on your
machine, so treat them as a starting point and not a guarantee.
If you want a single key with no modifier and you're on a Mac, the Globe/Fn
key is the one designed to work that way — and it's already your default.
Everything else needs a modifier.
## If it registers but doesn't do anything
That's a different problem — the shortcut saved fine and something is
intercepting it, or a permission is missing. See [my hotkey doesn't
work](/help/fix/hotkey-not-working).
## Related
* [Your hotkeys](/help/dictation/hotkeys)
* [Hold or tap](/help/dictation/hold-or-tap)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
# Dictation cleanup
Source: https://docs.openwhispr.com/help/dictation/cleanup
OpenWhispr tidies your dictation before pasting it — removing filler words, fixing grammar and punctuation. Here's what it changes and how to switch it off.
What gets pasted usually isn't the raw transcript. By default OpenWhispr runs
your dictation through a language model that, in the app's words, will *"remove
filler words, fix grammar, and polish punctuation."*
This is **on by default**. It's why dictation reads like writing rather than
like speech — and it's also why, occasionally, the text isn't quite what you
said.
## What it changes
Cleanup is meant to be conservative. It takes out the *ums* and *you knows*,
adds punctuation you didn't speak, fixes obvious grammatical slips, and leaves
your wording alone otherwise.
It does **not** rewrite your text into a different tone, answer questions, or
follow instructions you dictate. If that's happening, you're hitting the voice
agent rather than cleanup — see [the four things your voice can
start](/help/agent/voice-modes).
## Turning it off
Open **Settings**, choose **Language Models** under **AI Models**, then the
**Dictation Cleanup** tab. The switch is **Enable text cleanup**.
With it off you get the transcript as the speech-to-text model produced it —
filler words, no punctuation beyond what the model inferred, and none of the
tidying. Some people prefer this for note-taking, where fidelity matters more
than polish.
## Choosing the model
Cleanup has its own model, separate from the one used for transcription and
separate again from the voice agent's. On the same tab you can run it on:
* **OpenWhispr Cloud** — no setup, no API key
* **Cloud Providers** — your own key with OpenAI, Anthropic, Gemini, or Groq
* **Local** — an on-device model, fully private and offline
* **Self-Hosted** — your own OpenAI-compatible endpoint
* **Enterprise** — your organisation's AWS, Azure, or GCP account
A local model keeps the text on your machine, which matters if you dictate
anything sensitive. It's slower than cloud on most hardware.
## When cleanup fails
If the cleanup step can't run, your dictation is **pasted anyway**, uncleaned,
with a note saying *"Your dictation was pasted without AI cleanup."* You don't
lose the text — that's deliberate.
Recurring failures usually mean the model can't be reached: an expired API key,
no network, or a local model that hasn't finished downloading.
## Related
* [The four things your voice can start](/help/agent/voice-modes)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [Cloud vs local processing](/guides/cloud-vs-local)
# Hold or tap
Source: https://docs.openwhispr.com/help/dictation/hold-or-tap
Press once to start and again to stop, or hold the key while you speak. Which you can use depends on your platform.
OpenWhispr can start dictation two ways, and you choose which:
* **Tap** — press the hotkey to start, press it again to stop. This is the
default.
* **Hold** — hold the hotkey down while you speak, release to stop.
The setting is under **Settings** → **Hotkeys** under **App**, labelled
**Activation Mode**, directly beneath the dictation hotkey field.
## Which one to pick
Tap suits longer dictation — a paragraph, an email — because you aren't holding
a key for a minute. It also survives you pausing to think.
Hold suits short bursts, and it's harder to leave running by accident. If you've
ever walked away from a recording that was still going, hold fixes that
permanently.
## Where hold works
| Platform | Hold available? |
| -------- | -------------------------------------------------- |
| macOS | Yes |
| Windows | Yes |
| Linux | Only with keyboard input access set up (see below) |
## Linux setup
On Linux, hold needs permission to read keyboard input devices, which your user
account doesn't have by default. If it isn't set up you'll see **Hold to Speak
needs setup** in settings, with the command to run:
```bash theme={null}
sudo usermod -aG input $USER
```
Log out and back in afterwards — group membership isn't picked up until you do.
Until then the Hold option stays unavailable and dictation runs in tap mode.
## When the choice isn't offered
On Linux desktops where OpenWhispr hands shortcut registration to the desktop
environment — GNOME, KDE, or Hyprland — the app doesn't see the key being
released, only that it was pressed. Where that applies and the input-device
access above isn't in place, the mode is fixed at tap.
Everywhere else the control is always shown.
## Related
* [Your hotkeys](/help/dictation/hotkeys)
* [Choosing a shortcut that works](/help/dictation/choosing-a-shortcut)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
# Your hotkeys
Source: https://docs.openwhispr.com/help/dictation/hotkeys
OpenWhispr has five separate shortcuts, not one. Here's what each does, what it defaults to, and how to change or unbind it.
OpenWhispr listens for **five separate shortcuts**, each starting a different
thing. Most people only ever set the first one, but knowing all five exist
explains a lot of surprises — particularly getting an answer when you expected
your words typed.
They all live in one place: open **Settings**, then **Hotkeys** under **App**.
## The five shortcuts
| Shortcut | What it starts | Set by default? |
| ----------------------- | ----------------------------------------------------------- | --------------- |
| **Dictation Hotkey** | Voice to text. Your words are typed at the cursor. | Yes |
| **Voice Agent Hotkey** | Speak an instruction. The result is typed, not your words. | No |
| **Translation Hotkey** | Dictate in one language, get another one pasted. | No |
| **Meeting Mode Hotkey** | Starts meeting mode and snaps the panel to the screen edge. | No |
| **Chat Agent Hotkey** | Opens and closes the chat agent overlay. | No |
Only the **Dictation Hotkey** is set out of the box and it's the only one you
can't leave empty. The other four are blank until you choose a key, and clearing
one switches that feature off rather than breaking it.
The distinction that catches people out is between the first two. Dictation
types what you said. The voice agent, in the app's own words, means *"Speak a
request — your AI agent types the result, not your words."* If you're getting
replies instead of text, see [it answers me instead of
typing](/help/fix/it-answers-instead-of-typing).
## Defaults
The dictation shortcut is set for you on first run, and what you get depends on
your platform:
| Platform | Default dictation hotkey |
| -------- | ------------------------------------- |
| macOS | **Globe** (the Fn key on modern Macs) |
| Windows | **Ctrl+Win** |
| Linux | **Ctrl+Super** |
On macOS the Globe key is handled by a small listener bundled with the app
rather than by the normal shortcut system. That's why it can work as a single
key when everything else needs a modifier — and why, if that listener fails to
start, you'll see a **Globe Hotkey Unavailable** message and your other
shortcuts keep working.
If you've changed the dictation hotkey and want to go back, a **Reset to
\[key]** link appears under the field. It only shows when your current setting
differs from the platform default.
## Changing one
1. Open **Settings**, then **Hotkeys** under **App**.
2. Click the field under the shortcut you want — it shows **Click to set
hotkey** or **Click to change**.
3. Press the combination you want. The field reads **Listening…** while it
waits.
4. It saves as soon as it registers. You'll see **Now using \[key] for
dictation** for the dictation slot.
If the combination can't be used you'll get a reason rather than silence —
*"already registered by another application"*, *"may be reserved by your desktop
environment"*, or a note that the format isn't valid. [Choosing a shortcut that
works](/help/dictation/choosing-a-shortcut) covers the rules and what to pick
instead.
## More than one key for the same thing
Each shortcut accepts **several bindings at once**. Under any hotkey field
there's **Add another hotkey** — use it when you want the same action on, say,
both a keyboard shortcut and an external key, or when you switch between two
keyboards with different layouts.
There's one limit: on Linux desktops where OpenWhispr registers shortcuts
through the desktop environment itself — GNOME, KDE, or Hyprland — each action
takes **one binding only** and the option to add another disappears.
## Unbinding one
**Hover over the hotkey and click the bin icon.** It only appears on hover, and
only when a hotkey is actually set, which is why it's easy to miss.
That works for the four optional shortcuts. The **Dictation Hotkey** is
required — remove its last binding and it won't clear, because dictation with
no shortcut would leave you no way to start.
Unbinding the **Voice Agent Hotkey** is worth knowing about specifically: it
stops that shortcut, but it does **not** stop the agent being triggered by name
during ordinary dictation. Those are two different routes to the same feature —
see [your agent's name](/help/agent/agent-name).
## Hold or tap
Underneath the dictation hotkey there's an **Activation Mode** control with two
settings, **Tap** and **Hold**. Tap is the default. Which ones you can use
depends on your platform — [hold or tap](/help/dictation/hold-or-tap) has the
detail.
## Related
* [Choosing a shortcut that works](/help/dictation/choosing-a-shortcut)
* [Hold or tap](/help/dictation/hold-or-tap)
* [The four things your voice can start](/help/agent/voice-modes)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
# Getting better accuracy
Source: https://docs.openwhispr.com/help/dictation/improve-accuracy
Practical things that improve transcription quality — the engine you use, your microphone, your language setting, and teaching it your vocabulary.
If transcription is close but not right, there are four levers worth pulling, in
roughly the order they pay off.
## 1. Name your language
Auto-detect is the default, and it's the weakest setting for accuracy because
the model spends part of its effort deciding what language you're in. If you
nearly always dictate in one language, set it explicitly under **Settings** →
**Preferences** under **App**, in the **Language** section.
This is the single cheapest improvement for most people.
## 2. Teach it your words
Names, jargon, product names and acronyms are what transcription gets wrong most
often, and no amount of model tuning fixes a word the model has never seen.
The **custom dictionary** exists for this — add the terms you use and they'll be
recognised. See [custom dictionary](/help/customise/custom-dictionary).
If you've named your voice agent, its name is added to the dictionary
automatically so it's recognised reliably when you address it.
## 3. Check your microphone
The built-in microphone on a laptop is usually the weakest link, especially in a
room with any background noise. A headset — even a cheap one — is a bigger
improvement than changing models.
Pick which microphone OpenWhispr uses under **Settings** → **Preferences** under
**App**. If it isn't picking up at all, see [my microphone isn't
working](/help/fix/microphone-not-working).
Speaking at a normal pace helps more than speaking slowly and clearly. These
models are trained on natural speech, and over-enunciating is further from what
they expect, not closer.
## 4. Choose a better engine
Transcription runs on one of several engines, and they aren't equally accurate.
Set yours under **Settings** → **Speech-to-Text** under **AI Models**, on the
tab for the mode you're changing — **Dictation**, **Note Recording**, or
**Audio Upload**.
| Engine | Trade-off |
| -------------------- | ---------------------------------------------------------------------- |
| **OpenWhispr Cloud** | Most accurate, needs a connection |
| **Whisper (local)** | Private and offline; accuracy scales with model size and your hardware |
| **Parakeet (local)** | Faster than Whisper locally, fewer languages |
| **AssemblyAI** | Your own key, 7 languages |
If you're running a local model and accuracy is poor, a larger model is usually
the answer — see [local models](/guides/local-models).
## What cleanup does and doesn't fix
Dictation cleanup tidies grammar and punctuation, but it can't recover a word
that was misheard — it only sees the transcript, not your audio. Persistent
wrong words are a transcription problem, not a cleanup one.
## Related
* [Custom dictionary](/help/customise/custom-dictionary)
* [Dictating in other languages](/help/dictation/languages)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [Local models](/guides/local-models)
# Dictating in other languages
Source: https://docs.openwhispr.com/help/dictation/languages
Set the language you speak, use auto-detect, and see which languages each transcription engine supports.
OpenWhispr transcribes 60 languages, plus an auto-detect option. Which of them
are available depends on **which engine you're transcribing with** — they don't
all support the same set.
## Setting your language
Open **Settings**, then **Preferences** under **App**, and find the **Language**
section. There are two settings there and they do different things:
| Setting | What it controls |
| -------------------------- | ------------------------------------------------------------ |
| **Interface language** | The language OpenWhispr's own menus and buttons are shown in |
| **Transcription language** | The language you speak when dictating |
Changing the interface language does nothing to your dictation, and vice versa.
The app describes them as being set *"independently"* for exactly this reason.
Your transcription language applies everywhere — dictation, meeting notes, and
uploaded audio all use the same one.
The **engine** is a different matter and is set per mode: dictation, note
recording, and audio upload each choose their own under **Settings** →
**Speech-to-Text** under **AI Models**. So it's possible to be on Whisper for
dictation and Parakeet for uploads, and get different language coverage from
each — with one language setting feeding both.
## Auto-detect
**Auto-detect** is the default, and it works out the language from what you say.
It's the right choice if you switch languages regularly or use more than one in
a single passage.
Naming your language outright is more accurate than leaving it on auto,
particularly on short or noisy clips where there's less for the detector to go
on. If you nearly always dictate in one language, set it.
## What each engine supports
| Engine | Languages | Where it runs |
| -------------- | --------- | ---------------- |
| **Whisper** | 59 | Local or cloud |
| **Parakeet** | 26 | Local only |
| **AssemblyAI** | 7 | Your own API key |
Sixty distinct languages appear across all three, plus auto-detect. Whisper has
the widest coverage, so if a language you need isn't offered, check which engine
that mode is on first — moving from Parakeet to Whisper adds thirty-odd
languages.
You may see "100+ languages" on the OpenWhispr website. That refers to the
languages the underlying Whisper model family can handle. The number you can
actually **select** in the app today is 60.
## Getting the wrong language back
If you dictate in one language and get another, the usual causes are auto-detect
making a call on a short clip, or a mode running an engine that doesn't cover
the language you want. [The words come out
wrong](/help/fix/wrong-words-or-language) walks through it.
## Dictating in one language, pasting another
That's translation — a separate feature with its own hotkey. See
[translation](/help/dictation/translation).
## Related
* [Translation](/help/dictation/translation)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [Local models](/guides/local-models)
# Translation
Source: https://docs.openwhispr.com/help/dictation/translation
Dictate in one language and have the text pasted in another, using a dedicated hotkey.
Translation gives you a **second dictation hotkey** that does one extra thing:
before pasting, it translates. You speak in one language, the text that lands is
in another.
Your ordinary dictation hotkey is unaffected — it keeps pasting in the language
you spoke.
## Turning it on
Two things are needed, and it's easy to do one and not the other.
**1. Configure it.** Open **Settings**, choose **Language Models** under
**AI Models**, then the **Translation** tab:
* **Enable Dictation Translation** — the switch. Off by default.
* **Spoken language** — what you dictate in. **Automatic** here also copes with
dictation that mixes languages.
* **Target languages** — the languages you translate into. Add up to **5** and
mark one as active.
* **Translation Prompt** — how the model should translate, if you want to steer
it.
**2. Give it a key.** Open **Settings**, then **Hotkeys** under **App**, and set
the **Translation Hotkey**. Without a key there's no way to start a translated
dictation.
If you haven't chosen a target language, the hotkey stays inactive — the
settings tab says *"Pick a target language to activate the translation
hotkey."*
## Switching between languages
You can keep up to five target languages configured and switch which one is
live from the **Active target language** control, without re-entering settings
each time. Useful if you write to people in two or three languages regularly.
## Its own model
Translation uses a **separate model** from dictation cleanup — set on the same
Translation tab. So you can run cleanup on a local model and translation on a
cloud one, or the reverse.
Translated dictations are cleaned up first, then translated.
## Where translations show up
Translated entries are marked as such in your History, and you can re-run one
through the translation chain from the retry menu if the result wasn't what you
wanted.
## If translation fails
Your dictation is pasted **untranslated**, with a notice. It's never dropped —
you get the original text and can retry from History.
## Related
* [Dictating in other languages](/help/dictation/languages)
* [Your hotkeys](/help/dictation/hotkeys)
* [Dictation cleanup](/help/dictation/cleanup)
# Antivirus or firewall blocks OpenWhispr
Source: https://docs.openwhispr.com/help/fix/antivirus-blocks-openwhispr
Windows Defender or a security suite flagging the installer, quarantining bundled binaries, or prompting about the local server.
Security software flags OpenWhispr, or quietly removes parts of it after
installation. There are several separate versions of this and they look
different, so it's worth identifying which one you have.
## 1. The installer is flagged as suspicious
Windows SmartScreen, Norton, McAfee and similar products warn about applications
they haven't seen many times before. It's a reputation signal, not a detection —
new releases of any small application trigger it.
**What to do:** download only from [openwhispr.com](https://openwhispr.com) or
our [GitHub releases](https://github.com/OpenWhispr/openwhispr/releases), then
choose the option to keep or run it anyway. On Windows SmartScreen that's **More
info → Run anyway**.
If your security software reports a specific detection name rather than a
generic warning, please send it to us — we submit false positives to vendors,
and your report is what lets us do it.
## 2. Bundled components are quarantined
This is the one that produces confusing symptoms, because the app installs fine
and then fails at one specific task. OpenWhispr ships helper binaries, and
security software sometimes removes them **silently** afterwards:
| Binary | What breaks when it's removed |
| --------------------------------- | ------------------------------------------------------- |
| FFmpeg | Transcription fails immediately with "FFmpeg not found" |
| whisper.cpp | Local transcription doesn't work |
| `windows-system-audio-helper.exe` | Meeting audio falls back to microphone only |
| sherpa-onnx | Local Parakeet transcription fails |
**What to do:** add OpenWhispr to your antivirus exclusions, then reinstall so
the removed files come back. On Windows Defender that's **Windows Security →
Virus & threat protection → Manage settings → Exclusions**.
Reinstalling without adding the exclusion first usually just repeats the cycle.
## 3. A firewall prompt for the local server
The first time local Parakeet transcription runs, Windows may ask whether to
allow `sherpa-onnx-ws-win32-x64` on public and private networks.
**Either answer is safe.** The bundled server only serves OpenWhispr itself over
`127.0.0.1`, and Windows never filters loopback traffic — so transcription works
even if you click Cancel. The prompt appears because the server has no
loopback-only bind option, so Windows sees it listening on all interfaces.
All-users installations register a firewall rule that blocks outside access and
suppresses the prompt entirely. Per-user and portable builds may still see it
once.
## 4. The firewall blocks cloud transcription
If dictation fails with connection errors rather than a security warning, the
firewall is blocking outbound traffic rather than the application itself.
Allow OpenWhispr through Windows Firewall, and if you're on a managed network,
give your IT team the [network allowlist](/help/it/network-allowlist).
## FAQ
The desktop app is open source — you can read exactly what it does at
[github.com/OpenWhispr/openwhispr](https://github.com/OpenWhispr/openwhispr).
Downloads come from our own site and from GitHub releases.
Classic quarantine. A scheduled scan removed a bundled binary after
installation — section 2 above.
Ask IT to allowlist the application rather than individual files, and send
them the [network allowlist](/help/it/network-allowlist) at the same time so
both are handled together.
Whatever your security software shows — the exact string. That's what
vendors need for a false-positive submission.
## Related
* [OpenWhispr won't open](/help/fix/app-wont-open)
* [Network allowlist](/help/it/network-allowlist)
* [Local transcription isn't working](/help/fix/local-transcription-not-working)
# OpenWhispr won't open
Source: https://docs.openwhispr.com/help/fix/app-wont-open
Installed but no window appears, the app seems to be running invisibly, or the dictation panel is off-screen.
You launch OpenWhispr and nothing appears. Sometimes it's genuinely not
starting; more often it *is* running and you can't see it.
## Check the system tray or menu bar first
OpenWhispr runs from the tray, so the main window not being on screen is normal.
* **Windows** — click the `^` caret at the right of the taskbar to show hidden
icons, and look for the OpenWhispr icon there.
* **macOS** — look along the menu bar at the top right.
From the tray icon you can show the dictation panel and open Settings.
## If it's genuinely not starting
The process appears in Task Manager but no window ever shows.
Some graphics drivers stop Electron applications rendering at all. Launch
with:
```batch theme={null}
OpenWhispr.exe --disable-gpu
```
If that works, the graphics driver is the cause — updating it is the
real fix.
```batch theme={null}
OpenWhispr.exe --log-level=debug
```
Logs are written to `%APPDATA%\OpenWhispr\logs\`. Send us the newest
one.
Security software can quarantine parts of the app silently. See
[Antivirus blocks OpenWhispr](/help/fix/antivirus-blocks-openwhispr).
Uninstall, then remove the leftover data directories, then reinstall:
```batch theme={null}
rd /s /q "%APPDATA%\OpenWhispr"
rd /s /q "%LOCALAPPDATA%\OpenWhispr"
```
This deletes local settings, history and any downloaded models. Notes
you've backed up to the cloud are safe; anything local is not.
Look in the menu bar, and check the Applications folder for a second
copy of OpenWhispr — running an old copy alongside a new one causes odd
behaviour.
Running from the mounted `.dmg` rather than a proper install is a common
cause of the app behaving strangely. Drag it to Applications first.
```bash theme={null}
/Applications/OpenWhispr.app/Contents/MacOS/OpenWhispr --log-level=debug
```
This also prints startup errors straight to the terminal, which is often
the fastest answer.
Run the binary from a terminal and read what it prints — startup failures
are almost always visible there.
```bash theme={null}
openwhispr --log-level=debug
```
Logs are written to `~/.config/OpenWhispr/logs/`.
## The panel is off-screen
If dictation works but you can't see the panel — usually after unplugging an
external monitor — restart the app. That resets the panel's position. You can
then drag it wherever you want it.
## If you get a startup error
OpenWhispr shows **"OpenWhispr Startup Error"** or **"OpenWhispr failed to
load"** with an error code when it can't start properly. Send us that exact
message; it names the failure directly and saves a round of questions.
## Related
* [Antivirus blocks OpenWhispr](/help/fix/antivirus-blocks-openwhispr)
* [Updates and reinstalling](/help/fix/updates-and-reinstalling)
* [Windows](/platform/windows)
# Can't reach OpenWhispr Cloud
Source: https://docs.openwhispr.com/help/fix/cant-reach-openwhispr-cloud
Connection errors during setup or dictation — networks, corporate proxies and certificate warnings.
OpenWhispr tells you it can't reach the cloud — either during onboarding
(*"We can't reach OpenWhispr Cloud from this network"*) or when a dictation
fails (*"Can't reach OpenWhispr Cloud"*).
That's a network path problem rather than an account problem. Your notes and
local dictation are unaffected.
## Quick checks
Tethering to a phone for one dictation is the fastest diagnostic there is.
If it works there, the problem is the network you were on — which points at
a firewall, a DNS filter, or a proxy.
If it mentioned a **TLS handshake** — *"check your system clock or for a
corporate proxy"* — skip to
[Certificate and proxy errors](#certificate-and-proxy-errors).
A clock that's wrong by more than a few minutes breaks TLS outright. Set it
to update automatically.
Local models need no network at all. Set it per mode: **Settings** →
**Speech-to-Text** under **AI Models**, then the tab for the mode you're
using — **Dictation**, **Note Recording** or **Audio Upload**. See
[Local models](/guides/local-models).
## On a work or school network
Managed networks block by default, and OpenWhispr will be blocked along with
everything else new. What your IT team needs is the host list:
Every host the app contacts, with purpose and protocol — written to be
forwarded as-is.
The two that matter most are `api.openwhispr.com` and `auth.openwhispr.com`.
Without the second you can't sign in at all.
## Certificate and proxy errors
If you see a certificate error, a TLS handshake failure, or a warning about SSL
inspection, a proxy is intercepting the connection and its root certificate
isn't trusted by your operating system.
This is normal on corporate networks and it isn't something OpenWhispr can work
around — the fix is for the proxy's root certificate to be installed in the
system trust store, which your IT team will already do for other software.
Model downloads report this specifically: *"Certificate error — your network may
use SSL inspection that blocks downloads. Try downloading from a different
network."* That advice works, and it's often the quickest way to get a local
model installed before returning to the managed network.
## VPNs and security software
Any of these can sit in the path:
* **Corporate VPNs** that force all traffic through an inspecting gateway.
* **Consumer VPNs** whose exit node is blocked or rate-limited.
* **DNS filters and ad blockers**, including router-level ones — these produce
"could not resolve host" rather than a connection failure.
* **Endpoint security software** that inspects TLS.
Turn them off one at a time and retry. That identifies the one responsible
faster than reasoning about it.
## FAQ
Local processing does — transcription on a downloaded model needs no network
at all. Cloud transcription, sync and the cloud agent need the connection.
See [Cloud vs local](/guides/cloud-vs-local).
The app follows your system proxy settings, including PAC scripts, on every
platform. Configure it at the operating-system level and OpenWhispr picks it
up.
Then a filter is matching our hostnames specifically. Ask your IT team to
allowlist the hosts on the
[network allowlist](/help/it/network-allowlist) page — that's what it's for.
Both use `api.openwhispr.com`, so a partial failure usually means an
intermittent path rather than a block. A debug log will show which requests
failed — see [how to send one](/troubleshooting#send-us-a-debug-log).
## Related
* [Network allowlist](/help/it/network-allowlist)
* [A model won't download](/help/fix/model-download-fails)
* [Cloud vs local](/guides/cloud-vs-local)
# It says I hit a daily limit
Source: https://docs.openwhispr.com/help/fix/daily-limit-message
The free allowance is weekly, not daily — what the limit actually is, and when it frees up.
You hit the free-plan limit and OpenWhispr told you it was a **daily** one, with
advice to try again tomorrow.
**That message is wrong, and we're fixing it.** The free allowance is not daily
and waiting until tomorrow may not help.
## What the limit actually is
**2,000 words per rolling 7 days**, on OpenWhispr Cloud, on the free plan.
*Rolling* is the part that matters. There's no weekly reset day. At any moment
the app counts what you've transcribed in the previous seven days — so your
allowance frees up gradually, as individual transcriptions pass the seven-day
mark, rather than all at once on a particular morning.
So if you used your 2,000 words on a Monday, you get them back the following
Monday — not at midnight tonight, and not on whatever day you think of as the
start of the week.
Elsewhere in the app the same limit is labelled correctly as **"Weekly limit
reached"**. If you've seen both, they're the same limit — one label is simply
wrong, and we're fixing it.
## What still works when you've hit it
The limit applies to **OpenWhispr Cloud transcription only**. These are
unaffected:
* **Local models** — unlimited, on any plan, and they never touch the
allowance. See [Local models](/guides/local-models).
* **Your own API keys** — if you bring a key, that's your provider's quota, not
ours.
* **Everything you've already transcribed** — nothing is locked or deleted.
If you're hitting the limit regularly, moving dictation to a local model is the
change most people make, and it costs nothing.
## If you're on a paid plan and still see this
Then something is wrong rather than expected. Check
[I paid but still see the Free plan](/help/fix/paid-but-shows-free) first — it's
usually an account or session issue — and email us if that doesn't resolve it.
## FAQ
Expected, unfortunately, and it's exactly why the message is wrong. Waiting
helps only when a transcription from seven days ago rolls out of the window.
Your usage is shown in the app, and the limit indicator appears as you
approach it. [Plans and limits](/help/plans-and-limits) sets out every
allowance.
Yes. Usage is counted when the transcription runs, so deleting it afterwards
doesn't return the words.
See [Plans and limits](/help/plans-and-limits) for what each plan includes,
and [Changing your plan](/help/account/change-your-plan) for how to switch.
## Related
* [Plans and limits](/help/plans-and-limits)
* [Is OpenWhispr free?](/help/account/is-openwhispr-free)
* [I paid but still see the Free plan](/help/fix/paid-but-shows-free)
# My hotkey doesn't work
Source: https://docs.openwhispr.com/help/fix/hotkey-not-working
Nothing happens when you press the shortcut — conflicts, blocked keys, and the per-desktop rules on Linux.
You press your dictation shortcut and nothing happens. Almost always, another
application registered the same combination first — whoever asks the operating
system first wins, and OpenWhispr is told it can't have it.
Every hotkey lives in **Settings** → **Hotkeys** under **App**. That section
holds **Dictation Hotkey** and the separate shortcuts for **Voice Agent**,
**Translation** and **Meeting** recording.
## The defaults
| Platform | Default dictation hotkey |
| ----------------- | -------------------------------------- |
| macOS | the **Globe / Fn** key |
| Windows and Linux | **Ctrl** + **Super** (the Windows key) |
If the default can't be registered at startup, OpenWhispr tries **F8**, then
**F9**, then **Ctrl+Shift+Space** — so if your hotkey is one of those and you
never chose it, that's why.
## Quick checks
The fastest way to prove a conflict. Open **Settings** → **Hotkeys** under
**App**, set **Dictation Hotkey** to something unusual like
**Ctrl+Shift+K**, and try again. If that works, the original was taken.
Use **Add another hotkey** to bind a fallback. Both work, so you're covered
if one is claimed by an application you only sometimes run.
The hotkey field shows a **Shortcut Guide** with the rules and recommended
combinations for your platform. Some keys are refused outright — the app
lists them under **Blocked shortcuts**, because they're reserved by the
system.
Full-screen games, remote desktop sessions and virtual machines capture
keyboard input before anything else sees it. Test in a plain text editor to
rule this out.
## What makes a valid shortcut
The app enforces these, so a combination that breaks them won't save:
* It must include at least one modifier — Ctrl, Alt, Shift and so on.
* Three keys maximum.
* Single keys on their own aren't allowed.
* Reserved system shortcuts are refused.
Combinations that work well, by platform:
* **macOS** — Globe/Fn (the default), `Control+Option`, `Ctrl+Shift+K`
* **Windows** — Ctrl+Win (the default), `Ctrl+Alt`, `Ctrl+Shift+K`
* **Linux** — Ctrl+Super (the default), `Ctrl+Shift+K`, `Ctrl+Shift+J`
On **Linux**, three combinations the app's own Shortcut Guide suggests —
`Super+S`, `Ctrl+Alt+D` and `Alt+Space` — are on its reserved list and will be
refused. Use the ones above instead.
The best choices are the ones that type nothing if they slip through while
you're holding them — the platform defaults are all modifier-only or the Globe
key for exactly that reason.
## Tap or hold
**Activation Mode** in the same section decides how the key behaves:
* **Tap** — press once to start, press again to stop.
* **Hold** — hold the key while you speak, release to finish.
If dictation stops the instant you start speaking, or never stops, you're
probably in the other mode from the one you expect.
**Hold on Linux needs one-time setup.** Reading key-down and key-up events
requires access to input devices. The app tells you so — *"Hold to Speak needs
extra setup"* — and gives you the command:
`sudo usermod -aG input $USER`. Log out and back in afterwards.
## Linux desktops
GNOME doesn't let applications grab global shortcuts, so OpenWhispr
registers native GNOME shortcuts instead. Check **Settings → Keyboard →
Keyboard Shortcuts** for a conflict with an existing binding.
GNOME also requires a regular key rather than a modifier-only combination,
which is why F8 is the usual fallback there.
OpenWhispr writes its binds into your Hyprland config, so `hyprctl` must be
on your PATH.
Two things to know. First, OpenWhispr **claims** the combination you choose —
any existing Hyprland bind on the same keys is unbound when it registers.
Second, if the app can't write to your config file it warns that *"Hyprland
keybinds will not persist"*: they work now but won't survive a config
reload. Make sure the file exists and is writable.
KDE reports why a registration failed — either the combination is already
taken, or it's a modifier-only shortcut the system reserves. Pick a
combination with a regular key in it.
## FAQ
That app claimed the shortcut. Close it and try again to confirm, then
either change one of the two or add a second hotkey in OpenWhispr.
The operating system refused the combination — usually because it's already
taken or it's reserved. Choose another; the Shortcut Guide lists ones that
work.
If the one you set couldn't be registered at startup, OpenWhispr falls back
to F8, F9 or Ctrl+Shift+Space so dictation still works. Set it again and, if
it keeps happening, something else is taking it first.
Check that macOS isn't using it itself — **System Settings → Keyboard**,
where the **Press Globe key to** option can be set to change input source or
show emoji.
## Related
* [Choosing a shortcut that works](/help/dictation/choosing-a-shortcut)
* [Your hotkeys](/help/dictation/hotkeys)
* [How dictation works](/guides/dictation)
* [It answers me instead of typing](/help/fix/it-answers-instead-of-typing)
* [Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio)
# It answers me instead of typing what I said
Source: https://docs.openwhispr.com/help/fix/it-answers-instead-of-typing
You dictated a sentence and got a reply, a rewrite, or an answer to your question — here's which feature did it.
You dictated *"what time is the meeting tomorrow"* and instead of those words
appearing, you got an answer. Or you dictated a paragraph and what landed was a
tidied-up rewrite of it rather than what you actually said.
Three different features can process your speech, and each one has its own
switch. Working out which one is running takes a minute.
## 1. The voice agent
OpenWhispr has a **voice agent**: say its name and the rest of what you say is
treated as an instruction to carry out, not words to type. The app's own
description is *"When you say 'Hey \[agent name]' followed by an instruction, the
AI executes your command — composing content, formatting text, or answering
questions — instead of transcribing."*
So a dictation that begins with the agent's name is routed to the agent. If
your agent is called something ordinary, you can trigger it by accident just by
saying that word.
**Where to check:** **Settings** → **Language Models** under **AI Models**, then
the **Voice Agent** tab. **Enable voice agent** turns it off entirely, and
**Agent Name** is the word that triggers it.
If you want to keep the agent but stop the accidents, rename it to something
you'd never say by chance.
## 2. The Voice Agent hotkey
There's a **separate hotkey** for the agent, described in the app as *"Speak a
request — your AI agent types the result, not your words."*
If you used that shortcut instead of your dictation shortcut, you'll get an
answer every time. Turning off **Enable voice agent** disables this hotkey
too — they're the same feature — so if you've done that and still get
answers, the cause is something else on this page, not the toggle.
**Where to check:** **Settings** → **Hotkeys** under **App**. Compare
**Dictation Hotkey** with **Voice Agent Hotkey** and make sure they're not
similar enough to hit the wrong one.
## 3. Dictation cleanup
Separately from the agent, OpenWhispr can run your transcription through a
language model to tidy it — punctuation, filler words, obvious mis-hearings.
This is **Dictation Cleanup**, and it's what makes text come out polished rather
than verbatim.
Cleanup shouldn't answer questions. But it *is* the reason your words can come
back reworded, and if you want the raw transcription this is the switch.
**Where to check:** **Settings** → **Language Models** under **AI Models**, then
the **Dictation Cleanup** tab.
You can always see what was transcribed before any processing. In your
history, each item offers **View raw transcript** and **Copy raw transcript**.
Comparing the two tells you immediately whether the change happened during
transcription or afterwards.
## If you turned the agent off and it still happens
That's worth telling us about, and it's the version of this we most want to see.
Check in this order:
Turning off **Enable voice agent** disables the Voice Agent hotkey too, so
if you're still getting answers with the toggle off, double-check you
pressed the dictation hotkey and not the agent one.
If the raw transcript is your actual words and the final text is an answer,
something after transcription rewrote it. If the raw transcript is already
an answer, the request went to the agent.
Agent-name detection itself runs directly against your transcript, before
any prompt is involved — see [how naming it
works](/help/agent/agent-name#when-the-name-counts-as-addressing-it). The
placeholder warning in Prompt Studio is about something else: a custom
agent or cleanup prompt that drops the agent-name placeholder can still
behave unpredictably once the agent *is* triggered, so keep it if you've
edited that prompt.
It records which path the request took. That turns this from guesswork into
a single answer — see
[how to send one](/troubleshooting#send-us-a-debug-log).
## FAQ
Turn off **Dictation Cleanup** and **Enable voice agent**, both under
**Settings** → **Language Models** under **AI Models**. Transcription then
gives you what you said.
Yes — the voice agent can run on OpenWhispr Cloud, your own API key, a local
model, a self-hosted endpoint, or an enterprise provider. The mode is chosen
on the **Voice Agent** tab.
Because the trigger is what you said. A dictation that happens to start with
the agent's name is routed to the agent; one that doesn't, isn't.
## Related
* [AI agent mode](/guides/agent-mode)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
# Clipboard and system audio on Linux
Source: https://docs.openwhispr.com/help/fix/linux-clipboard-and-audio
Wayland clipboard behaviour, paste tools, and PipeWire capture — the two Linux-specific things that need setup.
OpenWhispr ships a native helper for pasting text into other applications, but
Wayland sessions and system-audio capture still depend on components Linux
distributions don't all ship.
Both are one-time setup, and the app tells you which pieces are missing.
## Clipboard and pasting
### The symptom
Pasting appears to work, but the target application shows nothing — or reports
*"clipboard is empty"*, *"no image on clipboard"*, or *"contents not available in
the requested format"*.
### Why
Electron's clipboard uses X11 selections through XWayland. Native Wayland
applications can't read those, so the text is on a clipboard your application
isn't looking at.
### The fix
The most reliable clipboard support on Wayland.
* Debian and Ubuntu: `sudo apt install wl-clipboard`
* Fedora and RHEL: `sudo dnf install wl-clipboard`
* Arch: `sudo pacman -S wl-clipboard`
OpenWhispr's native paste helper handles this automatically in the normal
case — nothing to install for X11. Install one of these only if the app
tells you the helper isn't available:
* **X11** — `xdotool`
* **Sway and Hyprland** — `wtype`
* **GNOME, KDE and other Wayland sessions** — `ydotool` (with the
`ydotoold` daemon running), which falls back to `xdotool` for XWayland
apps
* **KDE Wayland** — also `xclip` or `xsel`
It checks for these tools at runtime, so a restart usually isn't needed —
the status view under **Preferences** → **App** shows what it found. If
pasting still fails right after installing `ydotool` specifically, restart
OpenWhispr once; it caches how it talks to `ydotool` for the rest of the
session.
OpenWhispr tries clipboard methods in order — `wl-copy` first, then the
renderer's own clipboard, then X11 as a fallback.
On some Wayland sessions automatic pasting isn't possible at all. OpenWhispr
says so — *"Clipboard Mode on Wayland"* — and copies your text to the
clipboard so you can paste it with Ctrl+V. That's the
designed behaviour, not a failure.
The app reports the status of each component under **Settings** →
**Preferences** under **App**, so you can see exactly what's missing rather than
guessing.
## System audio
### The symptom
Meeting transcription records your microphone but not other participants,
browser audio, or anything else the computer is playing.
### The fix
System audio is captured through PipeWire, from the default sink monitor.
* Debian and Ubuntu: `sudo apt install pipewire libpipewire-0.3-0`
* Fedora and RHEL: `sudo dnf install pipewire pipewire-libs`
* Arch: `sudo pacman -S pipewire`
For the current session.
After installing or updating PipeWire packages.
Make sure the audio you want is playing through the default sink.
**No screen-share chooser appears, and none should.** On Linux, OpenWhispr
captures the default sink monitor directly through PipeWire — unlike macOS,
there's no permission dialog and no picker.
## Hold-to-speak
Holding a key to dictate needs access to keyboard input devices, which most
distributions don't grant by default. The app tells you — *"Hold to Speak needs
extra setup"* — and gives the command:
```bash theme={null}
sudo usermod -aG input $USER
```
Log out and back in afterwards.
## FAQ
Sway and Hyprland with `wtype` are the most straightforward. GNOME and KDE
both work, with the caveats above.
Check the `ydotoold` daemon is actually running — the tool alone isn't
enough. The status view under **Preferences** shows each component
separately for this reason.
Yes. Dictation and transcription work regardless; you paste manually with
Ctrl+V.
Auto-paste needs `ydotool` and `/dev/uinput` access, which NixOS grants
declaratively. The app detects NixOS and shows the configuration you need.
## Related
* [Linux](/platform/linux)
* [The text doesn't paste](/help/fix/text-not-pasting)
* [Meeting audio isn't captured](/help/fix/meeting-audio-not-captured)
# Local transcription isn't working
Source: https://docs.openwhispr.com/help/fix/local-transcription-not-working
Whisper or Parakeet failing on your own machine — models, GPU acceleration, and the per-mode setting people miss.
You've chosen a local model and transcription fails, falls back to the cloud, or
produces nothing.
**Check this first.** The transcription engine is set **per mode**. Dictation,
note recording and audio upload each have their own — so switching one to
local leaves the others exactly where they were.
**Settings** → **Speech-to-Text** under **AI Models**, then the tab for the
mode you're actually using: **Dictation**, **Note Recording** or **Audio
Upload**.
If you changed the setting and nothing changed, this is almost always why.
## Quick checks
Local transcription needs the model on disk. The model picker shows which
are installed. If a download failed, see
[A model won't download](/help/fix/model-download-fails).
As above — the right tab, not just the right section.
Large models need substantial memory. If a small one works and a large one
doesn't, that's the constraint, and the smaller model is a real answer
rather than a workaround.
Security software removing whisper.cpp, sherpa-onnx or FFmpeg breaks local
transcription specifically while leaving everything else working. See
[Antivirus blocks OpenWhispr](/help/fix/antivirus-blocks-openwhispr).
## GPU acceleration
If GPU acceleration fails — an unsupported card, or not enough video memory —
OpenWhispr **restarts on the CPU, retries the same request, and tells you it's
using CPU instead**. Your dictation still completes; it's slower.
If that happens every time, turn GPU acceleration off from the GPU card in the
transcription model picker. It removes the failed attempt and the delay it adds.
## What "local" does and doesn't need
* **No network** once the model is downloaded — as long as cloud fallback
(below) is off, which is the default.
* **No plan allowance** — local transcription doesn't count against your weekly
words on any plan.
* **Real CPU or GPU work** — so it's slower than cloud on modest hardware, and
a laptop on battery may throttle it.
[Cloud vs local](/guides/cloud-vs-local) sets out the trade-offs;
[Local models](/guides/local-models) covers the models themselves.
## FAQ
That only happens if cloud fallback has been enabled — it defaults to
off, so out of the box a failed local attempt just fails rather than
silently going to the cloud. If you're seeing this, a debug log will show
what's configured and why the local attempt failed — see
[how to send one](/troubleshooting#send-us-a-debug-log).
Expected on most machines. A smaller model is the usual answer if speed
matters more than the last few points of accuracy.
It depends on the model — Whisper and Parakeet support different sets.
[Local models](/guides/local-models) has the detail.
Local transcription runs on your machine and the audio doesn't leave it —
as long as cloud fallback is off, which is the default for every install.
If it's been enabled, a failed local attempt sends that audio to the
cloud instead of failing.
[Cloud vs local](/guides/cloud-vs-local) sets out what each mode sends.
## Related
* [Local models](/guides/local-models)
* [A model won't download](/help/fix/model-download-fails)
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
# Meeting audio isn't captured
Source: https://docs.openwhispr.com/help/fix/meeting-audio-not-captured
Only your voice is recorded, or nothing is — permissions, the Windows audio helper, and what to check per platform.
Your meeting recording contains your side of the conversation and nothing else,
or the transcript is empty.
Capturing other people means capturing **system audio** — what your computer is
playing — which is a separate thing from your microphone, with its own
permission on macOS and its own machinery on every platform.
OpenWhispr records what your computer plays. It never joins the meeting as a
bot, and on macOS it never records your screen.
## macOS
macOS gates system audio behind the same permission it uses for screen
recording, so the name you see in System Settings isn't the name the app uses.
**Settings** → **Privacy & Data** under **System** → **Permissions**. If
**System Audio** hasn't been granted yet, its card has a **Grant Access**
button that takes you to the right place. If the card is green with a
checkmark and shows no button, it's already granted — skip to the next step.
You'll land on **Privacy & Security → Screen Recording** — on recent macOS
versions it's labelled **Screen & System Audio Recording**. That's the
correct pane even though you're not recording your screen; macOS controls
both with one permission.
macOS only applies this permission to a fresh launch. If you granted it
while the app was running, quit and reopen it — this is the step most often
missed.
## Windows
System audio is captured by a bundled helper, `windows-system-audio-helper.exe`,
which needs no permission prompt and hears every application on every output
device. It requires **Windows 10 version 2004 or later**.
If the helper is missing or fails to start, OpenWhispr falls back to capturing
through Chromium, which only hears your **default output device**. So:
* **If you can hear the meeting but OpenWhispr can't**, check that the meeting
application is playing through your default output device — not a headset
you've selected only inside that app.
* **If you see "System audio capture failed. Continuing with microphone only"**,
system audio capture failed entirely. Your microphone is still being recorded;
everyone else isn't.
* **Check your antivirus hasn't quarantined the helper** — see
[Antivirus blocks OpenWhispr](/help/fix/antivirus-blocks-openwhispr).
**Microsoft Teams on Windows has been reported as an exception in some
setups.** In affected cases the Teams app renders audio in a way our
system-audio capture doesn't see, so a Teams meeting can record silence for
the other participants without reporting an error. This doesn't match how
the Windows capture path is designed to work (it's meant to hear every
application), so treat it as an open, unconfirmed issue rather than a fixed
limitation. Check a short test recording before relying on a Teams meeting,
and tell us your Teams and Windows versions if you hit this — that's what we
need to pin it down.
## Linux
System audio is captured through PipeWire, directly from the default sink
monitor. There's no screen-share chooser and you shouldn't expect one.
* Debian and Ubuntu: `sudo apt install pipewire libpipewire-0.3-0`
* Fedora and RHEL: `sudo dnf install pipewire pipewire-libs`
* Arch: `sudo pacman -S pipewire`
For the current session. Sign out and back in after installing or updating
the packages.
Confirm the meeting audio is playing through the default sink.
## If recording never starts at all
That's meeting **detection** rather than audio capture:
* Check **Meeting detection** is enabled — **Settings** → **Preferences** under
**App**, in the **Notifications** group.
* Keep talking for a few seconds. The prompt is triggered by *sustained*
microphone activity, not by having a meeting app open, so a very short
exchange may not reach it.
* Connect Google Calendar in Integrations if you want calendar-driven detection.
A scheduled event doesn't depend on hearing anything, which makes it the most
reliable trigger.
* You can always start recording by hand with the **Meeting Mode Hotkey**, or
from the in-app meeting prompt — an always-on-top card that works with Do Not
Disturb on and never appears in screen shares.
## FAQ
Because macOS has no separate system-audio permission — capturing audio your
computer plays is governed by the screen-recording permission. OpenWhispr
doesn't capture your screen; it only takes the audio.
Depends on where you and they are — recording laws vary and some
jurisdictions require everyone's consent. Worth knowing before you rely on
it.
On Windows, the fallback capture path only hears your default output device.
On macOS, the permission is almost always the answer. Both are covered
above.
Yes — that's what you get when system audio isn't available, and it's a
valid way to work if you only need your own side.
## Related
* [Meeting transcription](/guides/meeting-transcription)
* [My microphone isn't working](/help/fix/microphone-not-working)
* [Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio)
# My microphone isn't working
Source: https://docs.openwhispr.com/help/fix/microphone-not-working
Permission prompts that never appear, "No microphones detected", and the wrong input device — fixed per operating system.
Almost every microphone problem is one of two things: OpenWhispr doesn't have
permission to use the microphone, or your computer is listening to a different
one than you think.
Start in the app, because it can test and grant the permission for you.
## Start here
In **Settings**, choose **Privacy & Data** under **System**, and scroll to
**Permissions**. It lists **Microphone** — on macOS, also **Accessibility**
and **System Audio**.
If the permission is missing, the **Microphone** card shows a **Grant
Access** button that asks your operating system for it. If the permission has
never been requested, this is what triggers the prompt.
A card that has already been granted looks different: it turns green with a
checkmark and **the Grant Access button is gone**. That's how you tell the
two states apart — a card with no button is a granted one, not a broken one.
Follow the steps for your operating system below, then reopen this section —
the card shows as granted once your operating system agrees.
## Granting the permission
1. Open **System Settings → Privacy & Security → Microphone**.
2. Find **OpenWhispr** in the list and switch it on.
3. If OpenWhispr isn't listed at all, the permission has never been
requested — use **Grant Access** in the app to trigger the prompt.
4. Quit and reopen OpenWhispr. macOS applies microphone changes to running
apps inconsistently, and a restart removes the doubt.
After an app update, macOS can treat OpenWhispr as a new application and
drop the permission. If dictation stopped working right after an update,
that's what happened — see
[Updates and reinstalling](/help/fix/updates-and-reinstalling).
1. Open **Settings → Privacy & security → Microphone**.
2. Switch on **Microphone access**.
3. Switch on **Let apps access your microphone**.
4. Check that **Let desktop apps access your microphone** further down the
page is also on — this is the one that catches people out, because the
toggle above it can be on while this one is off.
5. Confirm OpenWhispr appears in the list underneath.
Linux has no per-application microphone permission, so there's nothing to
grant. What matters is which input device your sound server has selected.
1. Open your audio settings — `pavucontrol` on PulseAudio or PipeWire
systems is the most direct.
2. On the **Input Devices** tab, confirm the device you're speaking into
isn't muted and its level moves when you speak.
3. On the **Recording** tab, check that OpenWhispr is reading from that
device while a dictation is running.
## Choosing the right input
If the permission is granted and you still get nothing, the app is almost
certainly listening to a different microphone.
Open your operating system's sound settings and check the selected input while
you speak — the level meter should move. The devices that catch people out:
* **Headsets that are connected but not worn**, so the mic is on the desk.
* **Monitors and webcams with built-in mics**, which often become the default
the moment they're plugged in.
* **Bluetooth headphones in the wrong profile** — some switch to a low-quality
headset mode that other apps then take over.
* **Virtual devices** installed by conferencing or streaming software, which can
silently become the default.
## If the microphone is unavailable
If the app reports **Microphone Unavailable**, another application is holding
the device exclusively. Quit conferencing, recording and streaming apps and try
again. On Windows this is the usual cause; the device is not shared while
another app has it open in exclusive mode.
## FAQ
Use **Grant Access** in **Settings → Privacy & Data → Permissions**. macOS
and Windows only show the prompt when an app asks, and only once — after
that you have to change it in system settings yourself.
That rules out the hardware and tells you it's the permission or the device
selection. Work through both sections above; they're the only two things
that can be different between apps.
Raise the input level in your operating system's sound settings. A recording
that's too quiet produces an empty result rather than an error — see
[Nothing was transcribed](/help/fix/nothing-was-transcribed).
## Related
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
* [Meeting audio isn't captured](/help/fix/meeting-audio-not-captured)
* [Updates and reinstalling](/help/fix/updates-and-reinstalling)
# A model won't download
Source: https://docs.openwhispr.com/help/fix/model-download-fails
Downloads that fail, stall, or install incorrectly — and what each error message actually means.
You picked a local model and the download failed, stopped part way, or finished
and then wouldn't install.
The error you got narrows it down considerably, so start there.
## What each message means
| Message | What it means | What to do |
| ----------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Certificate error — your network may use SSL inspection** | A proxy is intercepting the download and its root isn't trusted | Download from a different network, or have IT trust the proxy root. See [Can't reach OpenWhispr Cloud](/help/fix/cant-reach-openwhispr-cloud) |
| **Server error** | The model host returned an error | Wait and retry — this is usually temporary and not on your side |
| **Model downloaded but installation failed** | The file arrived but couldn't be unpacked | Click download again. It reuses what you already downloaded rather than fetching it a second time |
| **Download failed** | A generic network failure | Check the connection and retry; see below if it keeps happening |
**"Model downloaded but installation failed" is worth retrying immediately.**
The app is explicit that retrying installs from the file you already have — so
it costs seconds, not another full download.
## If it keeps failing
Models are large, and a download that dies part way through is usually a
full disk. The larger Whisper models in particular need several gigabytes
free.
If a small model downloads and a large one doesn't, that's disk space or a
connection dropping over a long transfer — not a broken installation.
Corporate networks, VPNs and DNS filters block the model hosts more often
than they block anything else we use, because the files come from
`huggingface.co` and GitHub rather than from us.
In the model picker, delete the partial model, then download it fresh. That
clears a corrupted partial file, which retrying alone won't always fix.
## On a managed network
Model downloads need hosts that cloud transcription doesn't, so they can fail on
a network where everything else works. Your IT team needs:
* `huggingface.co`
* `cdn-lfs.huggingface.co`, `cdn-lfs-us-1.huggingface.co`
* `github.com`, `objects.githubusercontent.com`
The full list, with purpose and protocol, is on
[Network allowlist](/help/it/network-allowlist).
## FAQ
Yes — OpenWhispr Cloud works throughout, so you can keep dictating.
Only for local processing. Cloud transcription needs nothing downloaded.
[Cloud vs local](/guides/cloud-vs-local) covers the trade-off.
They're stored on your machine, and the model picker shows each one's size
before you download it. You can delete any of them from the same place.
That points at the install step failing rather than the download — the file
never lands where the app expects it. Send us a debug log; see
[how](/troubleshooting#send-us-a-debug-log).
## Related
* [Local models](/guides/local-models)
* [Local transcription isn't working](/help/fix/local-transcription-not-working)
* [Network allowlist](/help/it/network-allowlist)
# Nothing was transcribed
Source: https://docs.openwhispr.com/help/fix/nothing-was-transcribed
What "No Audio Detected" means, why an empty result happens, and how to get the take back.
You spoke, and either a **No Audio Detected** notice appeared — *"The recording
contained no detectable audio"* — or the dictation finished and produced
nothing at all.
Both mean the same thing from the app's side: no words came out of the audio it
had. That happens for a small number of reasons, and they're quick to separate.
**First, before you re-record anything:** if history is on, your audio is still
on disk and you can transcribe it again without repeating yourself. See
[I lost a dictation](/help/fix/recover-a-lost-dictation).
## Quick checks
The most common cause by far. Your computer may have switched inputs — to a
headset that isn't on your head, or to a monitor's built-in mic across the
room. Open **Settings**, choose **Privacy & Data** under **System**, and
look at the **Permissions** section to confirm the microphone is granted;
then check which input device your operating system has selected.
Full walkthrough: [My microphone isn't working](/help/fix/microphone-not-working).
Start a dictation and speak normally. If the app shows no movement at all,
the audio never reached it and the problem is the device or the permission,
not the transcription.
Very short takes — a word or two, or a hotkey pressed and released almost
immediately — often contain too little speech to produce a result. Try a
full sentence.
If you're on OpenWhispr Cloud, try a local model, or the other way around.
Whichever one works tells you where the problem is.
The engine is set **per mode** — dictation, note recording and audio upload
each have their own. Open **Settings**, choose **Speech-to-Text** under
**AI Models**, and use the **Dictation** tab for dictation.
## If your microphone was fine
A few situations produce a genuinely empty result even though audio was
captured:
* **The recording was silent or nearly silent.** A muted headset, a hardware
mute switch, or an input whose gain is at zero. Debug logs record the measured
level for exactly this reason.
* **Another app had exclusive hold of the microphone.** Conferencing apps are
the usual ones. Quit it and try again.
* **The audio wasn't speech.** Background noise on its own generally produces
nothing rather than nonsense, which is the intended behaviour.
## Get us the log
This is the case where a debug log settles it in one round instead of several.
It records the audio level the app measured, so it distinguishes "the microphone
sent silence" from "the microphone sent nothing" from "transcription ran and
returned empty" — three different fixes that look identical from the outside.
[How to send us a debug log](/troubleshooting#send-us-a-debug-log)
## FAQ
Usually not. History is on by default and audio is kept for 30 days, so you
can re-transcribe it — see [I lost a dictation](/help/fix/recover-a-lost-dictation).
The exception is a dictation you cancelled with Escape, which isn't kept
unless you've turned that on.
Check whether your default input device changed — plugging in headphones,
docking a laptop, or joining a call can move it. On macOS, an app update can
also require you to grant the microphone permission again; see
[Updates and reinstalling](/help/fix/updates-and-reinstalling).
That's a different problem — see
[The words come out wrong](/help/fix/wrong-words-or-language).
## Related
* [My microphone isn't working](/help/fix/microphone-not-working)
* [I lost a dictation](/help/fix/recover-a-lost-dictation)
* [Local transcription isn't working](/help/fix/local-transcription-not-working)
# I paid but still see the Free plan
Source: https://docs.openwhispr.com/help/fix/paid-but-shows-free
Your payment went through and the app hasn't caught up — what to check, and when to just email us.
You subscribed, the card was charged, and OpenWhispr is still showing the Free
plan or still enforcing the free weekly limit.
Nearly always this is one of four things, and the first two are the common ones.
**You will not be charged twice for sorting this out, and you won't lose the
subscription you paid for.** If none of the checks below fixes it, email us —
we can look at the account directly and it takes minutes.
## Check these in order
Payment confirmation reaches the app a few seconds after checkout, and
sometimes the window you were looking at doesn't refresh. Quit OpenWhispr
fully and reopen it. If you wrote to us within a couple of minutes of
paying, this is very likely all that happened.
The subscription attaches to the account you paid with. If you have more
than one address, it's easy to pay with one and be signed into the other.
**Settings** → **Account** under **Account** shows the email you're signed
in as. Compare it with the address on your payment receipt.
**Settings** → **Plans & Billing** under **Account**. If it shows the paid
plan here but the limit still bites, that's different from it showing Free —
tell us which one you're seeing, because they point in opposite directions.
This re-fetches your plan from scratch. It's the step that resolves a stale
session.
## If your plan comes from a workspace
You can have paid access without any subscription of your own — a workspace can
carry the plan and pay for your seat.
If your access comes that way, your personal billing shows as Free and that's
correct, not a fault. What matters is that you hold a seat in the workspace —
check **Settings** → **Workspace** under **Account**, and ask whoever set it up
whether your seat is active.
## When to just email us
Write to [support@openwhispr.com](mailto:support@openwhispr.com) if:
* You restarted, you're signed into the right account, and it still shows Free.
* You were **charged more than once** for the same plan.
* The plan appeared and then went back to Free on its own.
Include the email address on the payment and roughly when you paid. We can check
the payment and the account against each other and fix it from our side — you
don't need to cancel and resubscribe, and please don't, because that makes it
harder to untangle.
**If you were charged twice, tell us rather than cancelling.** A duplicate
charge is refundable and we'll do it — see [Refunds](/help/account/refunds).
Cancelling first can leave you without the plan you're paying for.
## FAQ
A minute or two, and a restart. Beyond that, write to us.
No. The plan follows your account, not the machine. Sign in on any device
and it applies.
If Plans & Billing shows a paid plan and you're still limited, that's worth
a debug log and an email — see
[It says I hit a daily limit](/help/fix/daily-limit-message).
Ask us. If you couldn't use what you'd paid for, we'll put it right.
## Related
* [Managing your subscription](/help/account/manage-your-subscription)
* [A payment failed](/help/account/payment-failed)
* [Plans and limits](/help/plans-and-limits)
# I lost a dictation
Source: https://docs.openwhispr.com/help/fix/recover-a-lost-dictation
Re-transcribe audio you already recorded, and recover a dictation you cancelled by mistake.
If a dictation produced nothing, errored, or you cancelled it by accident, the
audio is often still on your machine — you can transcribe it again without
saying it all over.
## Re-transcribe from history
Your recent dictations are listed in the control panel.
Failed items are marked, and a transcription that returned nothing appears
as an empty entry rather than disappearing.
The item's actions include **Re-transcribe**. It runs the saved audio
through transcription again.
If the failure was caused by something you've since fixed — a missing model, a
provider that wasn't set up, an expired session, no network — re-transcribing is
all you need.
If you see **"Audio file not found or expired"**, the recording is past its
retention period or was removed, and it can't be recovered.
## What's kept, and for how long
These are the defaults on a new install. All of them are in **Settings** →
**Privacy & Data** under **System**.
| Setting | Default | What it means |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| **Data Retention** | On | Transcriptions and audio are saved to your history. With this off, text is pasted but nothing is stored. |
| **Audio Retention** | 30 days | How long recordings stay on disk before they're deleted automatically. |
| **Transcript Retention** | Forever | Saved transcriptions aren't deleted on a schedule. |
| **Save discarded dictations** | **Off** | Whether a dictation you cancel with Escape is kept. |
Re-transcribing needs the **audio**, so it works for the last 30 days by
default. You can raise or lower that, or turn audio storage off entirely, in the
same place.
## Recovering a dictation you cancelled
By default, pressing Escape during a dictation discards it and the audio is not
kept — so a cancelled take is gone.
You can change that for next time. Switch on **Save discarded dictations** in
**Settings** → **Privacy & Data** under **System**. Cancelled dictations then
stay in your history and can be re-transcribed like any other.
It needs both **Data Retention** and **Audio Retention** to be on — the toggle
stays disabled otherwise, because there'd be nowhere to keep the audio.
## FAQ
On your own machine. The same section shows **Storage Usage** — how many
files and how much space — and **Clear All Audio** if you want them gone
now.
With **Data Retention** off, transcriptions are pasted but never saved, so
there's nothing to recover. The app says as much in the history view:
*"Data retention is off. Transcriptions and audio are not saved to
history."*
If it runs through OpenWhispr Cloud, yes — it's a new transcription. Running
it on a local model doesn't touch your allowance. See
[Plans and limits](/help/plans-and-limits).
Yes. Each history item offers **View raw transcript** and **Copy raw
transcript**, which give you the transcription before any cleanup was
applied.
## Related
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
* [The words come out wrong](/help/fix/wrong-words-or-language)
* [Plans and limits](/help/plans-and-limits)
# The text doesn't paste
Source: https://docs.openwhispr.com/help/fix/text-not-pasting
Transcription works but nothing appears in the app you're typing into — permissions, paste tools, and the clipboard fallback.
Your words were transcribed — you can see them in the app — but nothing landed
where you were typing.
**Your text isn't lost.** OpenWhispr puts it on the clipboard, so
Cmd+V or Ctrl+V pastes it right now
while you work out the rest.
## The fix, by operating system
Automatic pasting needs the **Accessibility** permission. Without it,
OpenWhispr can transcribe but can't type into another application.
**Settings** → **Privacy & Data** under **System** → **Permissions**.
The **Accessibility** card shows whether it's granted, and offers
**Grant Access** if not.
**System Settings → Privacy & Security → Accessibility**, then switch on
**OpenWhispr**.
This is the common case after an update or reinstall: macOS keeps a stale
entry that no longer matches the app. In the same **Permissions**
section, open **Troubleshooting** and use **Reset accessibility
permissions** — it removes OpenWhispr from the list so you can add it
back cleanly. Then grant it again in System Settings.
Windows needs no special permission for automatic pasting — the app says so
itself when you check permissions.
If text isn't pasting on Windows:
* Check **Automatic pasting** is on: **Settings** → **Preferences** under
**App** → **Clipboard**.
* Try pasting into a plain text field, like Notepad. Some applications —
particularly ones running as administrator, remote desktop sessions, and
games — refuse simulated input from a normal-privilege app.
* If it works in Notepad but not in your target app, that app is the
constraint, and the clipboard is your route into it.
OpenWhispr ships a native paste helper and tries it first — on X11 that's
the normal case and needs nothing installed. It falls back to an external
tool only where the helper can't be used (mainly Wayland, which needs
`/dev/uinput` access the helper may not have):
* **X11** — falls back to `xdotool` if the helper isn't available.
* **Wayland** — `wtype` on Sway and Hyprland, or `xdotool`/`ydotool`
(with the `ydotoold` daemon running) on GNOME, KDE and other sessions.
* **KDE Wayland** — also install `xclip` or `xsel`.
The app checks what's available at runtime, so a restart usually isn't
needed after installing a tool — **Settings** → **Preferences** under
**App**, in the Wayland paste section, shows what it found. One exception:
if you install `ydotool` after a first failed paste, restart OpenWhispr
once — it caches how it talks to `ydotool` for the rest of the session.
On some Wayland sessions automatic pasting isn't available at all. OpenWhispr
tells you this directly — *"Clipboard Mode on Wayland"* — and copies your
text to the clipboard instead. That's the expected behaviour, not a failure.
Clipboard trouble specifically is covered in
[Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio).
## If you'd rather paste manually
Turn **Automatic pasting** off and keep the text on the clipboard instead:
**Settings** → **Preferences** under **App** → **Clipboard**. Switch on **Keep
transcription in clipboard** so your dictated text stays there until you paste
it.
This is also the workaround if you're hitting
[text pasted twice](/help/fix/text-pasted-twice).
## FAQ
That's the target application refusing simulated input rather than a problem
with OpenWhispr. Elevated applications, remote desktop clients and some
games all do this. Use the clipboard for those.
Paste manually with Cmd+V or
Ctrl+V — the text is on the clipboard. Then work
through the permission steps above for your operating system.
Turn off **Keep transcription in clipboard** and OpenWhispr restores your
previous clipboard contents after pasting.
## Related
* [Dictating into other apps](/platform/dictating-into-other-apps)
* [Editors, IDEs and terminals](/platform/editors-and-terminals)
* [My text is pasted twice](/help/fix/text-pasted-twice)
* [Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio)
* [Updates and reinstalling](/help/fix/updates-and-reinstalling)
# My text is pasted twice
Source: https://docs.openwhispr.com/help/fix/text-pasted-twice
Dictated text arriving duplicated on Windows — what to do now, and where the fix stands.
Your dictation finishes and the same text lands twice in a row.
**This is a confirmed bug on Windows, not a setting you've got wrong.** We're
working on it. What follows is how to stop it happening to you in the meantime.
## Work around it now
The most reliable option, and it costs one keystroke.
**Settings** → **Preferences** under **App** → **Clipboard**, then switch
off **Automatic pasting**.
Switch on **Keep transcription in clipboard** in the same section so your
dictated text stays there after each take.
Once, where you want it.
If your dictation hotkey is a modifier-only combination — the default on
Windows is **Ctrl + Super** — try a combination containing a regular key,
such as **Ctrl+Alt+Space** or **Ctrl+Shift+K**.
Set it in **Settings** → **Hotkeys** under **App**.
Worth trying because modifier-only shortcuts are handled by a different
input path on Windows than ordinary combinations. If it makes a difference
for you, tell us — that's a useful data point.
## Help us fix it
If you're hitting this, a debug log is genuinely valuable — it records the paste
path taken and how many times it ran, which is what separates a duplicated
keystroke from a duplicated transcription.
[How to send us a debug log](/troubleshooting#send-us-a-debug-log)
Tell us as well:
* Your Windows version, and whether the target app runs as administrator.
* The exact hotkey you use, and whether Activation Mode is tap or hold.
* Whether it happens in every application or only some.
## FAQ
Check your history. If the entry appears once but the text landed twice, the
paste ran twice. If there are two entries, the dictation itself ran twice —
which usually means the hotkey fired twice, and changing it is the fix.
We've only had it reported on Windows. If you're seeing it elsewhere, please
tell us — that would change what we're looking at.
## Related
* [The text doesn't paste](/help/fix/text-not-pasting)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)
# Updates and reinstalling
Source: https://docs.openwhispr.com/help/fix/updates-and-reinstalling
Updates that fail, permissions that stop working afterwards, and how to reinstall without losing anything you need.
Most update problems fall into two groups: the update itself failing, or
everything working afterwards *except* the permissions.
## Permissions stopped working after an update
This is the common one, and it's macOS behaviour rather than a bug.
When the app is replaced, macOS can treat it as a **new application** and stop
honouring the permissions you'd granted the old one. Dictation then produces
nothing, or automatic pasting stops, with no error explaining why. OpenWhispr
tells you when it detects this: *"Your notes and settings carried over from the
previous version. macOS treats this as a new app though, so a few permissions
need to be granted again."*
**Settings** → **Privacy & Data** under **System** → **Permissions**. Each
card shows whether it's granted, with **Grant Access** where it isn't.
macOS keeps a stale entry pointing at the old application. In the same
section, open **Troubleshooting** and use **Reset accessibility
permissions** — it removes OpenWhispr from the list. Then add it back in
**System Settings → Privacy & Security → Accessibility**.
Several macOS permissions only take effect on a fresh launch.
## Checking your version
**Settings** → **System**, under **Updates** — the number is shown next to
**Current version**, with **Check for Updates** below it. Include it whenever
you write to us — it's the first thing we look at.
Updates are delivered automatically. If you see **Update Error**, note the
message and try again later; if it persists, downloading the current version
from [openwhispr.com](https://openwhispr.com) and installing over the top works
and keeps your data.
## Reinstalling
Installing a new version over an existing one keeps your settings, history and
downloaded models. That's the normal path and it's safe.
A **clean** reinstall — removing the data directories too — is a bigger step:
Removing the data directories deletes local settings, dictation history and
downloaded models. Notes backed up to the cloud come back when you sign in.
Anything local does not.
Uninstall from **Settings → Apps**, then:
```batch theme={null}
rd /s /q "%APPDATA%\OpenWhispr"
rd /s /q "%LOCALAPPDATA%\OpenWhispr"
```
Then install again.
Move OpenWhispr from Applications to the Trash, then remove
`~/Library/Application Support/OpenWhispr` if you want a clean state.
Reinstall, then re-grant permissions as above.
Remove the package as installed, then `~/.config/OpenWhispr` for a clean
state.
## Before you wipe anything
Worth checking first, because it's usually unnecessary:
* **Cloud backup** — if it's on, your notes are safe. **Settings** → **Privacy &
Data** under **System**.
* **Audio and transcripts** are local. A clean reinstall removes them.
* **Downloaded models** will need downloading again, which on a slow connection
is the most annoying part.
## FAQ
Not if cloud backup is on — they come back when you sign in. Notes that were
never backed up are local only, so a clean reinstall removes them.
No. Your plan follows your account. Sign in and it applies.
Older releases are on
[GitHub](https://github.com/OpenWhispr/openwhispr/releases). If you're
downgrading because something broke, please tell us what — that's worth more
to us than the downgrade is to you.
Updates roll out over a period. If you need the newest version immediately,
install it from [openwhispr.com](https://openwhispr.com) over the top.
## Related
* [The text doesn't paste](/help/fix/text-not-pasting)
* [My microphone isn't working](/help/fix/microphone-not-working)
* [OpenWhispr won't open](/help/fix/app-wont-open)
# The words come out wrong
Source: https://docs.openwhispr.com/help/fix/wrong-words-or-language
Names and jargon mis-heard, the wrong language, or accuracy that dropped — what to change, in order.
Transcription is working, but what lands isn't what you said. Names come out
mangled, technical terms are guessed at, or the whole thing is in the wrong
language.
These have different fixes, so it's worth knowing which one you have.
## Names, jargon and acronyms
If it's specific words that are wrong — people's names, product names, medical
or legal terms — the custom dictionary is the fix, and it's the highest-value
change you can make.
Add the words you use in **Dictionary** in the sidebar, on the **Dictionary**
tab. Type them into the box at the top — you can paste several at once,
separated by commas — and press **Add**. They're then supplied to transcription
so it knows to expect them.
Full guide: [Custom dictionary](/help/customise/custom-dictionary).
Add the spelling you want, not the one you're getting. The dictionary tells
transcription what the right answer looks like.
## The wrong language
Check the language set for the mode you're using. The engine and its language
are configured **per mode** — dictation, note recording and audio upload each
have their own — so changing it in one place doesn't change the others.
**Settings** → **Speech-to-Text** under **AI Models**, then the tab for the mode
you're using: **Dictation**, **Note Recording** or **Audio Upload**.
Auto-detect works from the audio, so a short or quiet take gives it very
little to go on. If you consistently work in one language, setting it
explicitly is more reliable than auto-detect.
## Accuracy that used to be better
Work through these in order — the first two account for most of it.
Local and cloud models differ in accuracy, and so do the local model sizes.
If you switched to a smaller local model, or fell back to one, that alone
explains a drop. **Settings** → **Speech-to-Text** under **AI Models**, then
your mode's tab.
Local models are covered in [Local models](/guides/local-models); the
trade-offs between local and cloud are in
[Cloud vs local](/guides/cloud-vs-local).
Accuracy is dominated by input quality. A headset microphone near your mouth
outperforms a laptop or monitor microphone across the room by a wide margin,
and a device change you didn't intend is common — see
[My microphone isn't working](/help/fix/microphone-not-working).
If the transcription is right but the final text isn't, something rewrote it
afterwards. Compare with **View raw transcript** in your history, and see
[It answers me instead of typing](/help/fix/it-answers-instead-of-typing).
Other voices, music and typing all degrade transcription. If you can't
change the environment, get closer to the microphone.
## If a whole passage is missing
A very long dictation can display truncated in the app even though the full
text was saved. Open the history item and use **View raw transcript** or **Copy
raw transcript** — that gives you everything, and it's the reliable route for
long recordings.
## FAQ
Larger models are more accurate and slower; smaller ones are faster and less
accurate. [Local models](/guides/local-models) sets out the options and what
each needs from your machine.
That's exactly what the custom dictionary is for. Add it there rather than
changing model.
You can re-run it — each history item offers **Re-transcribe**, which is
useful after you've added dictionary words or changed model. See
[I lost a dictation](/help/fix/recover-a-lost-dictation).
Adding words to your custom dictionary is the reliable way to teach it.
Everything about how that works is in
[Custom dictionary](/help/customise/custom-dictionary).
## Related
* [Custom dictionary](/help/customise/custom-dictionary)
* [Cloud vs local](/guides/cloud-vs-local)
* [Nothing was transcribed](/help/fix/nothing-was-transcribed)
# Getting help
Source: https://docs.openwhispr.com/help/getting-help
How to reach us, what to include so we can fix it fast, and where to report a bug.
Email **[support@openwhispr.com](mailto:support@openwhispr.com)**. A real person
reads every message, on every plan — including the free one.
## What to include
Most of the back-and-forth in a support thread is us asking for three things.
Send them up front and we can usually answer on the first reply:
macOS, Windows or Linux, and which version.
Open **Settings**, choose **System**, and read the number shown under
**Current version** in the **Updates** group.
The app you were dictating into, the file you uploaded, or the meeting you
were recording — and what happened instead of what you expected.
If something failed silently, a screenshot of the error or the relevant part of
your logs helps. See [Common problems](/troubleshooting) for where logs live on
your platform.
## Where to go for what
| You want to | Go here |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Ask a question, report a problem, or sort out billing | [support@openwhispr.com](mailto:support@openwhispr.com) |
| Cancel, refund, or change your plan | [support@openwhispr.com](mailto:support@openwhispr.com) — see [Plans and limits](/help/plans-and-limits) |
| Ask other users, or watch what's being built | [Discord](https://discord.gg/yZWC9WTtX7) |
| File a reproducible bug or a feature request as a developer | [GitHub Issues](https://github.com/OpenWhispr/openwhispr/issues) |
| Report a security vulnerability | [support@openwhispr.com](mailto:support@openwhispr.com), and please don't open a public issue |
You never have to open a GitHub issue to get help. It's there because OpenWhispr
is open source and some people prefer it — email is the front door.
## What happens next
Support on your plan works like this:
| Plan | Support |
| ---------- | ------------------------------- |
| Free | Community — Discord, plus email |
| Pro | Email |
| Business | Priority |
| Enterprise | Dedicated |
We reply to everything that arrives at [support@openwhispr.com](mailto:support@openwhispr.com). Cancellations and
refunds inside our published policy are usually handled the same day.
## Privacy
Please don't paste passwords, API keys or payment card details into a support
email. If we need something sensitive to help you, we'll tell you a safe way to
send it.
# Managed Amazon Bedrock and Azure OpenAI
Source: https://docs.openwhispr.com/help/it/managed-enterprise-ai
Configure customer-owned Bedrock or Azure OpenAI access once so employees only need company SSO.
Managed enterprise AI gives employees access to your AWS Bedrock or Azure OpenAI models without distributing cloud keys or asking them to configure a CLI. IT establishes trust once; OpenWhispr issues a short-lived, workspace-scoped identity after company SSO.
Prompts travel directly from the desktop app to your cloud account. OpenWhispr's API supplies identity and policy, but it does not proxy or store the prompt or response.
## Get an Enterprise workspace
Enterprise onboarding is currently sales-assisted. The first IT administrator creates an OpenWhispr account in the desktop app and creates the customer workspace. OpenWhispr then activates that existing workspace as Enterprise and confirms its owner. The owner opens the admin portal and configures SSO, SCIM, policy, and cloud trust. Employees do not configure any of those systems: once IT assigns them, they choose company SSO and receive their workspace, teams, and managed models automatically.
## How access works
1. Your identity provider assigns the employee through SCIM, or SSO admits them through the temporary just-in-time fallback during a pilot.
2. The employee signs in to OpenWhispr with company SSO.
3. OpenWhispr issues a five-minute assertion for that workspace and provider.
4. AWS STS or Microsoft Entra exchanges it for short-lived cloud access.
5. The desktop sends the model request directly to Bedrock or Azure OpenAI.
AWS credentials are requested for 15 minutes. Azure access tokens remain only in desktop memory until Microsoft expires them. Signing out, changing accounts, or changing workspaces clears the local credential cache.
An OpenWhispr login proves who the person is. Access to an Enterprise workspace is checked separately: the API also requires current workspace membership, the correct company SSO provider, the SCIM assignment when enforced, and the workspace policy. Switching workspaces repeats that authorization check.
## Before you start
You need:
* an active OpenWhispr Enterprise workspace; SSO, SCIM, and managed cloud access are not enforced on Business or Pro workspaces
* a verified SAML or OIDC provider; managed cloud assertions require a current company SSO session
* SCIM directory sync, recommended with just-in-time fallback off after rollout
* permission to create AWS IAM federation or a Microsoft Entra workload identity
* deployed and approved models in the cloud region or Azure resource you will use
Open **Policies > Managed enterprise AI** in the OpenWhispr admin portal. The page shows the exact issuer, audience, subject, and trust JSON for your workspace. Copy those generated values; do not type a workspace ID by hand.
Activate one managed provider at a time. You may save both configurations, but Bedrock and Azure OpenAI cannot both be active for the same workspace.
## Configure Amazon Bedrock
In AWS IAM, add an OpenID Connect identity provider. Use the issuer shown by OpenWhispr as the provider URL and `sts.amazonaws.com` as its audience.
AWS must be able to reach the issuer discovery and JWKS endpoints over HTTPS. See [AWS's OIDC provider guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).
Create a web-identity IAM role in the same AWS account as the OIDC provider. Grant access only to the models or inference profiles your workspace needs.
Typical runtime actions are `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`. If employees may browse the Bedrock catalog, also allow `bedrock:ListFoundationModels` and `bedrock:ListInferenceProfiles`.
Cross-region inference needs permission for both the inference-profile ARN and its destination foundation-model ARNs. Make sure organization SCP region restrictions permit every destination, and review the destination geography with your security and data-residency teams before rollout.
Enter the role ARN in OpenWhispr. The admin portal generates a trust policy constrained to the OpenWhispr issuer, `sts.amazonaws.com` audience, and `workspace:` subject.
Copy that policy to the IAM role. These conditions prevent an assertion for another workspace from assuming it.
Enter the AWS region and each allowed Bedrock model or inference profile ID, one per line. Commercial AWS and AWS GovCloud are supported; the role ARN partition must match the region. AWS China is not supported. The managed desktop configuration cannot invoke a model outside this list.
Choose a default for dictation cleanup, dictation agent, note formatting, note chat, and translation.
Save the provider as **Configured, not active**, allow Bedrock under **Policies > AI providers**, and select **Validate cloud access**. OpenWhispr verifies the AWS identity exchange and Bedrock control-plane access. The employee pilot confirms that the permitted model or inference profile can run; invocation permissions and destination-region service control policies still apply.
Start the pilot with **Managed by default** and leave **Allow manual setup** on. Have a SCIM-assigned employee sign in with company SSO. When the pilot succeeds, turn manual setup off or choose **Managed required**. Revalidate after changing any trust or provider value.
## Configure Azure OpenAI
Create a Microsoft Entra app registration or a user-assigned managed identity. Do not create a client secret.
Record the Entra tenant ID and the application's client ID, or the user-assigned identity's client ID.
On the intended Azure OpenAI resource, assign the workload identity the **Cognitive Services OpenAI User** role. Scope the assignment to the resource where possible.
Azure role changes can take several minutes to propagate. See [Microsoft's Azure OpenAI Entra authentication guide](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/how-to/managed-identity?view=foundry-classic).
In OpenWhispr, enter the tenant ID and client ID. Copy the generated federated credential JSON.
Add it under **Federated credentials** on the app registration or user-assigned managed identity. The issuer, subject, and `api://AzureADTokenExchange` audience are case-sensitive and must match exactly. Choose the **Other issuer** scenario when the portal asks.
Enter the Azure OpenAI HTTPS endpoint and use API version `v1` for stable APIs, or `preview` only when a required feature is preview-only. Add each permitted deployment name, one per line, then choose a default deployment for all five OpenWhispr features.
Enter only the public Azure resource origin, such as `https://acme.openai.azure.com`. Do not add `/openai`, `/openai/v1`, a deployment path, query parameters, or credentials. OpenWhispr adds the API path itself. Azure Government and other Azure clouds are not currently supported.
Save Azure as **Configured, not active**, allow it under **Policies > AI providers**, and select **Validate cloud access**. OpenWhispr verifies the Entra token exchange and access to the exact Azure OpenAI resource.
Start with **Managed by default** and **Allow manual setup** on, then test with a SCIM-assigned employee using a fresh company SSO session. After the pilot, turn manual setup off or choose **Managed required**. Revalidate after changing any tenant, identity, endpoint, version, or deployment value.
## Choose a rollout mode
| Rollout | Employee experience | When to use it |
| ---------------------- | ----------------------------------------------------------------------- | --------------------------- |
| Configured, not active | Saved for later; desktop behavior is unchanged | Prepare or stage a provider |
| Managed by default | Company SSO selects the administrator's provider and model defaults | Pilot and gradual migration |
| Managed required | Managed access is locked; personal profiles and keys cannot override it | Enforced production policy |
Any active managed mode requires a verified company SSO provider and a workspace policy that allows the selected enterprise cloud. **Managed required** also requires **Require SSO** and a successful validation of the exact cloud configuration within the previous 30 minutes. The admin portal shows these checks before it allows activation.
**Allow manual setup** preserves the existing AWS profile/access-key and Azure API-key flow during migration. Existing manual users are not silently switched until managed access becomes required. Employees without a manual configuration receive the managed provider by default.
## Rotate, switch, or roll back
* **AWS role change:** create the new role and apply the generated trust policy, enter the new ARN and validate the draft, save it, then remove the old trust.
* **Azure identity change:** create the new identity, add the generated federated credential and resource role, enter its client ID and validate the draft, save it, then remove the old credential or role assignment.
* **Model change:** add the new model or deployment, set all affected defaults, save, then remove the old item.
* **Provider switch:** save the inactive provider first, set the active provider to **Configured, not active**, then activate the other. The API prevents two active providers.
* **Emergency rollback:** choose **Configured, not active**. Existing manual access remains available only when your policy and **Allow manual setup** permit it.
Configuration changes advance a workspace-wide generation. Desktops refresh the non-secret configuration when the app regains focus and at least every five minutes while it is open. A newer generation invalidates older in-flight credentials and requests. AWS credentials, Azure access tokens, and OpenWhispr workload assertions are never persisted to disk.
For an emergency that cannot wait for desktop refresh, revoke the AWS role trust or Microsoft Entra federated credential or role assignment. That stops new cloud credentials for the entire workspace. Existing AWS credentials can last up to 15 minutes; Azure tokens last until the expiry Microsoft issued.
## Self-hosted API requirements
If you self-host the OpenWhispr API, configure one stable public HTTPS base URL before creating cloud trust. The generated issuer, discovery URL, JWKS URL, and workload assertions must all use that same origin. AWS and Microsoft must be able to reach the discovery and JWKS endpoints with a valid public TLS certificate; private hosts, changing preview URLs, and deployment aliases that rewrite the issuer are not suitable. Rotate signing keys with an overlap period so previously issued assertions can still be verified until they expire.
## Troubleshooting
| Message | What to check |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Company SSO is required | Sign out and sign back in with the company SSO option, not email or social login |
| Directory assignment required | The employee is active in SCIM and their SSO email matches the directory record |
| AWS cannot assume the role | OIDC issuer, audience, subject, role ARN, and trust policy match the generated values |
| Bedrock access denied | IAM actions, resource ARNs, region, model access, and inference profile permissions |
| Microsoft identity exchange failed | Tenant/client IDs and all federated credential fields match exactly; allow time for propagation |
| Azure OpenAI access denied | The identity has the correct inference role on the intended resource and the deployment name is exact |
| Provider is disabled by policy | Enable the selected enterprise provider under **Policies > AI providers** |
| Cloud validation is required | Select **Validate cloud access** again, then activate **Managed required** within 30 minutes without changing the configuration |
## Related
* [Provision people and teams with SCIM](/help/it/scim-provisioning)
* [Network allowlist](/help/it/network-allowlist)
* [Where your voice and text go](/help/privacy/where-your-data-goes)
# Network allowlist
Source: https://docs.openwhispr.com/help/it/network-allowlist
Every host the OpenWhispr desktop app contacts, for firewall, proxy and DNS-filter configuration.
This is the page to hand your IT team. It lists every outbound host the
OpenWhispr desktop app contacts, why, and whether it's optional.
All connections are client-initiated over TLS on port 443. A few components
— the CLI bridge, an auth bridge, an OAuth callback catcher, and local model
servers when you use them — listen on `127.0.0.1` for the app's own pieces to
talk to each other. One exception: the bundled Parakeet speech server can't
bind loopback-only, so on Windows it listens on all interfaces until the
installer's firewall rule closes it off — see [antivirus and firewall
prompts](/help/fix/antivirus-blocks-openwhispr).
## Required by default
Contacted by every install using OpenWhispr Cloud, which is the default after
onboarding.
| Host | Protocol | Purpose |
| --------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `api.openwhispr.com` | HTTPS | Cloud API — transcription, sync, agent reasoning, settings, usage |
| `auth.openwhispr.com` | HTTPS | Account sign-in and session refresh |
| `github.com`, `objects.githubusercontent.com` | HTTPS | Application auto-update (release artifacts) |
## Streaming transcription
Streaming sessions are routed through one of three providers. Allowlist all
three unless a specific provider is pinned in your configuration.
| Host | Protocol | Purpose |
| -------------------------- | ---------- | ------------------------------------------------------------- |
| `api.deepgram.com` | WSS | Deepgram streaming transcription |
| `api.openai.com` | WSS, HTTPS | OpenAI Realtime streaming transcription |
| `streaming.assemblyai.com` | WSS, HTTPS | AssemblyAI streaming — token endpoint HTTPS, live session WSS |
## Local model downloads
Contacted only when someone opts into a local model — Whisper, Parakeet, or a
local reasoning model. Not needed for cloud-only installs.
| Host | Protocol | Purpose |
| ------------------------------------------------------- | -------- | ------------------------------------------------------- |
| `huggingface.co` | HTTPS | Model downloads |
| `cdn-lfs.huggingface.co`, `cdn-lfs-us-1.huggingface.co` | HTTPS | Large-file CDN for model files |
| `github.com`, `objects.githubusercontent.com` | HTTPS | sherpa-onnx, llama.cpp, whisper.cpp and Qdrant binaries |
## Google Calendar (optional)
Only if a user connects Google Calendar in settings.
| Host | Protocol | Purpose |
| ----------------------- | -------- | -------------------------------------- |
| `accounts.google.com` | HTTPS | OAuth authorisation |
| `oauth2.googleapis.com` | HTTPS | OAuth token exchange and revoke |
| `www.googleapis.com` | HTTPS | Calendar event and calendar-list reads |
| `openwhispr.com` | HTTPS | OAuth desktop callback redirect |
## Company SSO and SCIM (optional)
Required only for centrally managed Enterprise workspaces. Business and Pro workspaces keep their ordinary sign-in flow.
| Direction | Host | Protocol | Purpose |
| -------------------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| Employee device outbound | Your SAML or OIDC provider host | HTTPS | Company browser sign-in |
| Employee device outbound | `api.openwhispr.com` | HTTPS | SSO discovery, workspace provisioning, policy, and short-lived workload assertions |
| Identity provider outbound | `api.openwhispr.com` | HTTPS | SCIM 2.0 provisioning below the workspace-specific base URL |
The SCIM connector is an inbound HTTPS integration from your identity provider to OpenWhispr. It does not require an inbound firewall rule on employee devices. See [SCIM provisioning](/help/it/scim-provisioning).
## Managed enterprise AI (optional)
Allow only the provider selected by your workspace administrator. Replace `` and the Azure wildcard with the region and resource you actually use.
| Host | Protocol | Used when |
| ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `api.openwhispr.com` | HTTPS | Fetch managed configuration and five-minute workload assertions |
| `sts..amazonaws.com` | HTTPS | Exchange a Bedrock assertion for 15-minute AWS credentials |
| `bedrock..amazonaws.com` | HTTPS | List permitted Bedrock models and inference profiles |
| `bedrock-runtime..amazonaws.com` | HTTPS | Send Bedrock model requests directly from the desktop |
| `login.microsoftonline.com` | HTTPS | Exchange an OpenWhispr assertion for an Azure access token |
| `.openai.azure.com` | HTTPS | Validate the configured public Azure OpenAI resource and send model requests directly from the desktop |
AWS and Microsoft also retrieve OpenWhispr's OIDC discovery document and public signing keys from `api.openwhispr.com`. That is cloud-to-cloud traffic, not a connection from the employee device.
## URL audio import (optional)
Only when a user pastes a URL into the Upload view. Downloads are HTTPS-only,
and hosts resolving to private or internal addresses are rejected.
| Host | Protocol | Purpose |
| ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `www.youtube.com`, `youtube.com`, `youtu.be`, `m.youtube.com`, `music.youtube.com` | HTTPS | YouTube page and metadata fetch |
| `*.googlevideo.com` | HTTPS | YouTube media CDN — the audio stream itself |
| *user-pasted hosts* | HTTPS | Direct audio or video URL imports contact whatever public host is pasted |
## Bring-your-own-key providers (optional)
Required only where a user has configured their own API key. Skip any provider
not in use.
| Host | Protocol | Used when |
| -------------------------------------------------------------------------------- | ---------- | ---------------------------------------------- |
| `api.openai.com` | HTTPS | OpenAI key configured |
| `*.cognitiveservices.azure.com`, `*.openai.azure.com`, `*.services.ai.azure.com` | HTTPS | Azure AI Foundry / Azure OpenAI speech-to-text |
| `api.anthropic.com` | HTTPS | Anthropic key configured |
| `generativelanguage.googleapis.com` | HTTPS | Gemini key configured |
| `api.groq.com` | HTTPS | Groq key configured |
| `atc.tinfoil.sh`, `*.tinfoil.sh` | WSS, HTTPS | Tinfoil key configured |
| `api.mistral.ai` | HTTPS | Mistral key configured |
| `openrouter.ai` | HTTPS | OpenRouter selected as a reasoning provider |
| `api.x.ai` | HTTPS | xAI (Grok) key configured |
| `ai.eu.corti.app` | HTTPS | Corti key configured |
Tinfoil assigns an enclave host dynamically at runtime, so allowlist
`*.tinfoil.sh` rather than pinning individual hosts. `atc.tinfoil.sh` serves
the attestation bundle, which is verified locally.
## Notes for network administrators
* **Proxies are honoured.** The app uses Electron's network stack, which follows
system proxy settings — macOS System Settings, Windows Internet Options and
WPAD, GNOME proxy — and PAC scripts on all platforms.
* **IP pinning is not supported.** These hosts resolve to provider-managed
addresses that change without notice. Allowlist by hostname.
* **TLS interception needs its root trusted by the OS.** Otherwise connections
fail with certificate errors.
* **Minimal Linux containers** without a system CA bundle — Alpine, distroless —
need `NODE_EXTRA_CA_CERTS` set to your CA bundle path.
### What the failures look like
| Symptom | Cause |
| ----------------------------------------------------- | ---------------------------------------------------------------------------- |
| `ENOTFOUND` | DNS is filtered — a resolver, filter or ad blocker is blocking the domain |
| `ECONNREFUSED` / `ETIMEDOUT` | A firewall is blocking the host or port |
| `CERT_HAS_EXPIRED`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE` | A TLS-intercepting proxy is in the path and its root isn't trusted by the OS |
## Testing the path
Run these from a machine on the same network as the user. **Any** HTTP response
— including `401` — confirms the network path works.
```sh theme={null}
# 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
```
## Related
* [Can't reach OpenWhispr Cloud](/help/fix/cant-reach-openwhispr-cloud)
* [A model won't download](/help/fix/model-download-fails)
* [Provision people and teams with SCIM](/help/it/scim-provisioning)
* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Enterprise](/guides/enterprise)
# Provision people and teams with SCIM
Source: https://docs.openwhispr.com/help/it/scim-provisioning
Connect Microsoft Entra ID, Okta, or another SCIM 2.0 directory so employees are ready before their first OpenWhispr sign-in.
SCIM lets your identity provider create and deactivate OpenWhispr workspace members and keep group membership in sync. After setup, an assigned employee signs in with company SSO and their workspace, teams, and managed AI settings are already available.
## Before you start
You need:
* an active OpenWhispr Enterprise workspace with owner or admin access
* a verified company domain connected to SAML or OIDC under **Security > Single sign-on**
* administrator access to your identity provider
* enough workspace seats for the people you assign
Keep **Allow just-in-time fallback** on during your pilot. Existing employees can continue to join through verified company SSO even if they have not been pushed through SCIM yet.
## Connect your directory
In the OpenWhispr admin portal, open **Security > Directory sync**, explicitly select the verified SSO provider for this directory, and select **Enable directory sync**. Pause directory sync before moving the connection to another verified provider.
Select **Create token**, then copy both the **SCIM base URL** and token. The full token is shown once and expires after 90 days by default. Store it in your identity provider, not in a shared document or ticket.
Use the SCIM base URL as the tenant or connector URL and the token as a bearer token. Then configure the attributes and actions below.
In the enterprise application you use for OpenWhispr, open **Provisioning**, choose automatic provisioning, and enter the OpenWhispr tenant URL and secret token.
Use **Sync only assigned users and groups** for a controlled rollout. Test the connection, assign a pilot group, then start provisioning.
In the OpenWhispr application, enable SCIM provisioning and enter the OpenWhispr base URL and bearer token.
Enable **Create users**, **Update user attributes**, **Deactivate users**, and **Push groups**. Assign a pilot group before expanding the rollout.
Configure a SCIM 2.0 bearer-token connector. OpenWhispr supports Users, Groups, PATCH, filtering, pagination, and ETags. Bulk requests, password changes, and sorting are not supported.
Send these standard SCIM attributes:
| OpenWhispr field | SCIM attribute | Requirement |
| ------------------- | ------------------------------------- | ------------------------------- |
| Work email | `userName` and primary `emails.value` | Required; must be a valid email |
| Directory object ID | `externalId` | Recommended |
| Status | `active` | Required for deprovisioning |
| Full name | `displayName` | Recommended |
| Name parts | `name.givenName`, `name.familyName` | Optional |
Group pushes use `displayName`, `externalId`, and `members[].value`.
Return to **Security > Directory sync**. Confirm that the assigned people and groups appear, then have a pilot employee choose company SSO in the desktop app.
Their first SSO session links the pre-provisioned directory record to their OpenWhispr identity. No invitation, API key, AWS profile, or Azure key is required.
After every intended employee is visible in the directory table, turn off **Allow just-in-time fallback**. Then enable **Require SSO** under **Security > Single sign-on**.
Turning off the fallback removes every non-owner workspace member who does not have an active linked directory record, including their workspace-team memberships. The confirmation shows the exact number first. Verify the directory table before continuing.
From that point, only active people assigned by your directory can enter the workspace, and password or social sign-in cannot be used for the verified domain.
Enabling it also ends sessions that did not come through your IdP, so an admin who signed in with a password is returned to sign-in to re-authenticate. The workspace owner keeps admin-console access without an SSO session, so a misconfigured IdP can always be undone.
## What each directory change does
| Identity-provider change | OpenWhispr result |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Assign an active user | Reserves a workspace seat and prepares the account before first login |
| Update a user's name or email | Updates the directory record |
| Add a user to a pushed group | Adds the linked employee to the matching team |
| Remove a user from a pushed group | Removes them from that team |
| Deactivate or delete a user | Removes workspace and team access at any role except owner; it does not delete the person's global OpenWhispr account |
| Push a group | Creates or updates a SCIM-managed team |
| Delete a group | Archives the SCIM-managed team so its history is preserved |
SCIM-managed teams are read-only in the OpenWhispr admin portal. Change their names and membership in your identity provider so the two systems do not drift.
Directory changes take effect when the identity provider sends the next successful SCIM request. Scheduled sync timing and retries are controlled by that provider, so a change made in Entra or Okta may not appear immediately. For urgent offboarding, revoke the employee's IdP session, run an on-demand provisioning cycle, and verify that the person is inactive in the OpenWhispr directory table. Deactivation removes cloud workspace and team access when OpenWhispr receives it; it does not remotely erase notes already stored on an employee device.
## Supported SCIM operations
The connection exposes `/Users`, `/Groups`, `/ServiceProviderConfig`, `/Schemas`, and `/ResourceTypes` below the base URL shown in the admin portal.
| Resource | Supported operations |
| ---------- | ---------------------------------------------------------------------- |
| Users | List, create, get, replace, patch, and deactivate |
| Groups | List, create, get, replace, patch, and delete |
| Filters | Single `eq` lookup by ID, external ID, username, or group display name |
| Pagination | `startIndex` and `count`, up to 200 results per page |
Requests are limited to 600 per minute per directory connection. A `429` response includes `Retry-After`.
## Rotate or revoke a token
Select **Rotate token** to create a second active token. Update the identity provider, run a test sync, then revoke the old token. Keeping both active for the short cutover avoids an interruption.
Tokens expire after 90 days by default. Revocation is immediate, and an expired or revoked token cannot provision or deactivate anyone.
## Troubleshooting
| Symptom | What to check |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Connection test returns `401` | The bearer token is complete, has not been revoked, and belongs to this workspace |
| Provisioning returns `409` | The workspace has an available seat and the email or `externalId` is not already assigned to another record |
| Employee is told they are not assigned | Their SCIM record is active, their SSO email matches `userName`, and just-in-time fallback is configured as intended |
| Group membership is missing | Push the group after its users and confirm member references use the OpenWhispr SCIM user IDs |
| SSO works but managed AI does not | The employee used company SSO for the current session and the managed provider is active |
## Related
* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Enterprise providers](/guides/enterprise)
* [Network allowlist](/help/it/network-allowlist)
# Capturing both sides of the call
Source: https://docs.openwhispr.com/help/meetings/capture-both-sides
Why recording the other participants is separate from recording your microphone, and what OpenWhispr does and doesn't capture.
A meeting recording has two halves: your voice, from your microphone, and
everyone else's, from what your computer is playing. They're captured by
different means and they can fail independently — which is why a recording
sometimes contains only you.
## What OpenWhispr captures
**Your microphone**, and **system audio** — the sound your computer plays.
Together those cover both sides of a call.
What it does **not** do:
* It never **joins the meeting as a bot**. Nobody sees an extra participant, and
there's nothing for a host to admit.
* It never **records your screen**, on any platform. On macOS the permission is
labelled for screen recording because macOS governs both with one control, but
only the audio is taken.
* It doesn't need the meeting platform's own recording to be running, and it
doesn't ask the host for permission.
## The permission it needs
System audio is permissioned separately from your microphone:
| Platform | What's needed |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **macOS** | The screen-recording permission, listed on recent versions as **Screen & System Audio Recording**. OpenWhispr only takes the audio |
| **Windows** | No prompt — a bundled helper does the capture. Needs Windows 10 version 2004 or later |
| **Linux** | PipeWire, capturing from the default sink monitor |
Granting it on macOS also requires **restarting OpenWhispr** — macOS applies the
permission at launch, and skipping the restart is the single most common reason
this doesn't work.
The step-by-step for each platform, including what to do when it fails, is in
[meeting audio isn't captured](/help/fix/meeting-audio-not-captured).
## Echo, and why you don't hear yourself twice
Your microphone picks up your speakers as well as your voice, so a naive
recording captures everyone else twice — once from system audio, once bleeding
back through your mic. OpenWhispr runs echo cancellation to remove that bleed,
and drops duplicated phrases when merging the two sources.
You don't need to configure this. It's worth knowing because it explains why a
transcript doesn't repeat every sentence, and why using headphones — which
removes the bleed at source — tends to give the cleanest result.
## Recording only your own side
If system audio isn't available, recording still works; you just get your half.
That's a legitimate way to work if you only need your own contributions, and
speaker labels will fall back to "You" and "Them".
**Check before you rely on it.** If a recording matters, start one, say a few
words, have someone else say a few, and stop. Ten seconds tells you whether
both sides are landing — and there is one known case, Microsoft Teams on
Windows, where the other side can come through silent without any error. That
case is documented in
[meeting audio isn't captured](/help/fix/meeting-audio-not-captured).
## Telling people you're recording
Recording laws vary by country and state, and some require the consent of
everyone on the call rather than just you. OpenWhispr doesn't announce itself to
other participants, so whether and how to tell them is your call to make.
## Related
* [Meeting audio isn't captured](/help/fix/meeting-audio-not-captured)
* [Record a meeting](/help/meetings/record-a-meeting)
* [Speaker labels](/help/meetings/speaker-labels)
* [Where your data goes](/help/privacy/where-your-data-goes)
# Connect Apple Calendar
Source: https://docs.openwhispr.com/help/meetings/connect-apple-calendar
Read meetings straight from Calendar.app on macOS — iCloud, Google, Exchange, and Outlook in one place.
On macOS you can connect **Calendar.app** instead of signing in to Google. Any
account already set up in Calendar — iCloud, Google, Exchange, Outlook — comes
through in one go, and nothing leaves your Mac to make it work.
Like [Google Calendar](/help/meetings/connect-google-calendar), it's optional.
Meeting recording works without it; a calendar adds titles, attendees, and a
prompt that appears because a meeting is *scheduled* rather than because
OpenWhispr heard something.
Apple Calendar is macOS only. On Windows and Linux, connect Google Calendar
instead.
## Connect it
Click **Integrations** in the sidebar, then the **Calendar** section.
Choose **Connect Apple Calendar**. macOS asks for calendar access the first
time — approve it and the card shows a **Connected** badge.
If you decline the prompt, the card explains that **Calendar Access** is
required and offers **Open System Settings**, which takes you to
**Privacy & Security → Calendars**. Turn OpenWhispr on there and it connects.
## Which one should you use?
| | Apple Calendar | Google Calendar |
| --------------------- | ---------------------------------- | --------------------------------- |
| Platforms | macOS only | macOS, Windows, Linux |
| Signing in | None — reads Calendar.app | Sign in to each Google account |
| Accounts covered | Everything in Calendar.app at once | One Google account per connection |
| Where reading happens | On your Mac | Through Google's API |
If your work calendar is already in Calendar.app, Apple Calendar is the simpler
choice.
## What it changes
| Without a calendar | With one connected |
| ----------------------------------------------------- | ----------------------------------------------------------------- |
| Prompt appears when OpenWhispr hears sustained speech | Prompt also appears just before a scheduled meeting |
| Notes start as **New note** | Notes take the event's title |
| Speaker count starts at a default | Attendees pre-fill the expected speaker count |
| You join the call yourself | **Join & transcribe** opens the link and starts the note together |
## System audio still needs its own permission
Connecting a calendar doesn't let OpenWhispr hear the other people on the call.
That's a separate operating-system permission —
[capturing both sides of the call](/help/meetings/capture-both-sides) walks
through it.
## Disconnecting
In the same panel, choose **Disconnect** on the Apple Calendar card and confirm.
Meeting notes stop being recorded from your Apple Calendar; notes you already
recorded are untouched, and microphone-based prompts and the Meeting Mode
Hotkey keep working.
Revoking access entirely is done in **System Settings → Privacy & Security →
Calendars**.
## Related
* [Connect Google Calendar](/help/meetings/connect-google-calendar)
* [How meeting detection works](/help/meetings/how-meeting-detection-works)
* [Record a meeting](/help/meetings/record-a-meeting)
* [Where your data goes](/help/privacy/where-your-data-goes)
# Connect Google Calendar
Source: https://docs.openwhispr.com/help/meetings/connect-google-calendar
Link your calendar so meeting notes arrive titled, with attendees filled in and a one-click join.
Connecting a calendar is optional — meeting recording works without it. What it
adds is context: notes that arrive already named, attendee lists that pre-fill
speaker labels, and a prompt that appears because a meeting is *scheduled*
rather than because OpenWhispr heard something.
## Connect it
Click **Integrations** in the sidebar, then the **Calendar** section.
Choose **Connect Google Calendar** and sign in with the Google account whose
calendar you want. You'll be asked to approve access in your browser.
**Sync primary calendar only** ignores events from calendars other people
have shared with you. Leave it on if colleagues' calendars would otherwise
fill your list with meetings you're not in.
You can connect more than one account — **Add another calendar** repeats the
process. The panel shows the **Google Calendar** card with a **Connected**
badge, one row per connected account showing its email address, and the
**Sync primary calendar only** switch.
## What it changes
| Without a calendar | With one connected |
| ----------------------------------------------------- | ----------------------------------------------------------------- |
| Prompt appears when OpenWhispr hears sustained speech | Prompt also appears just before a scheduled meeting |
| Notes start as **New note** | Notes take the event's title |
| Speaker count starts at a default | Attendees pre-fill the expected speaker count |
| You join the call yourself | **Join & transcribe** opens the link and starts the note together |
## System audio still needs its own permission
Connecting a calendar doesn't give OpenWhispr the ability to hear the other
people on the call. That's a separate operating-system permission, and the
integration panel will say so — *"To transcribe meetings, OpenWhispr needs the
System Audio permission to capture other participants"* — with an
**Open System Settings** button.
[Capturing both sides of the call](/help/meetings/capture-both-sides) walks
through it per platform.
## Disconnecting
In the same panel, hover over the row showing the account's email address. A
small unlink icon appears at the right-hand end of that row — click it. Nothing
on the panel is labelled "Disconnect", and the icon stays invisible until you
hover, so the row looks like it has no controls at rest.
You'll then be asked to confirm, and that dialog *is* labelled **Disconnect**.
Afterwards that calendar stops producing meeting prompts and stops filling in
titles and attendees; notes you already recorded are untouched.
Disconnecting is the right move if you connected a work account and are
leaving, or if you'd rather OpenWhispr didn't read a calendar at all. It
doesn't disable meeting recording — the microphone-based prompt and the
Meeting Mode Hotkey keep working.
## Related
* [How meeting detection works](/help/meetings/how-meeting-detection-works)
* [Record a meeting](/help/meetings/record-a-meeting)
* [Where your data goes](/help/privacy/where-your-data-goes)
# How meeting detection works
Source: https://docs.openwhispr.com/help/meetings/how-meeting-detection-works
What makes the take-notes prompt appear, why it sometimes doesn't, and how to turn it off.
OpenWhispr watches for the start of a meeting and offers to take notes. It's on
by default. Nothing is recorded until you accept the prompt.
## What actually triggers the prompt
Two things:
| Signal | What it is |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sustained microphone activity** | You've been talking for long enough that it looks like a call rather than a stray noise. This is what catches browser meetings — Google Meet, or anything running in a tab |
| **A calendar event** | If you've connected Google Calendar (or Apple Calendar on macOS), an event with a start time coming up produces a prompt shortly before it begins |
Both land in the same place, so overlapping signals give you **one** prompt
rather than several.
OpenWhispr also notices when Zoom, Microsoft Teams, Webex or FaceTime are
running, but that on its own does **not** produce a prompt — it's only used as
context. Having Zoom open in the background all day won't nag you.
## When the prompt says different things
The wording follows what OpenWhispr knows:
* **"It sounds like you're in a meeting."** — detected from your microphone
* **"Your meeting is starting."** — a calendar event about to begin
* **"It sounds like your meeting is underway."** — a calendar event already in progress
When the event carries a meeting link, the button becomes **Join & transcribe**
and opens the call for you.
## When it stays quiet on purpose
The prompt is suppressed when it would be unwelcome or redundant:
* You're **already recording** a meeting
* You're **mid-dictation** — the prompt waits rather than interrupting you, and
arrives once you've finished
* There's a short **cool-down** after you finish a recording, so ending one call
doesn't immediately prompt you about the same audio
* You already **dismissed** that particular detection
## Turning it off
Open **Settings**, then **Preferences** under **App**, and find
**Notifications**. Two separate switches:
| Setting | Controls |
| ---------------------- | -------------------------------------------------- |
| **Meeting detection** | The prompt triggered by microphone activity |
| **Calendar reminders** | The prompt triggered by an upcoming calendar event |
They're independent, so you can keep calendar reminders and drop the microphone
prompts, or the reverse. **Disable all notifications** in the same group
silences both — along with everything else except error messages.
Switching the prompt off doesn't remove the feature — you can still start a
meeting note whenever you like with the
[Meeting Mode Hotkey](/help/meetings/record-a-meeting).
## If you never get a prompt
Work through these in order:
1. **Check the switches above.** Both are on by default, but they're the first
thing to rule out.
2. **Talk for a bit longer.** Microphone detection waits for *sustained* audio
deliberately — a one-line "can you hear me?" may not be enough.
3. **Check your microphone is the one being used.** If OpenWhispr is listening to
a device you aren't speaking into, it hears nothing. See
[choose your microphone](/help/customise/choose-your-microphone).
4. **Connect your calendar** if your meetings are scheduled. Calendar events
don't depend on hearing anything at all, which makes them the most reliable
trigger — see [connect Google Calendar](/help/meetings/connect-google-calendar)
or [connect Apple Calendar](/help/meetings/connect-apple-calendar) on macOS.
If it still never fires, start the note by hand with the Meeting Mode Hotkey
and [tell us](/help/getting-help) — that's a bug worth hearing about.
## Related
* [Record a meeting](/help/meetings/record-a-meeting)
* [Connect Google Calendar](/help/meetings/connect-google-calendar)
* [Connect Apple Calendar](/help/meetings/connect-apple-calendar)
* [Meeting audio isn't being captured](/help/fix/meeting-audio-not-captured)
# Meeting hours on your plan
Source: https://docs.openwhispr.com/help/meetings/meeting-hours-on-your-plan
How many hours of meeting recording each plan includes, and what else applies while you record.
Each plan comes with an allowance of meeting recording:
| Plan | Meeting recording |
| -------------- | ----------------- |
| **Free** | 5 hours a month |
| **Pro** | 20 hours a month |
| **Business** | Unlimited |
| **Enterprise** | Unlimited |
## What else applies while you record
Your meeting allowance isn't the only thing in play, and the other pieces are
worth knowing because they're what you're most likely to actually notice:
* **Cloud transcription counts words.** On the Free plan, transcription through
OpenWhispr Cloud is limited to **2,000 words per rolling 7 days**, and meeting
transcription draws on the same allowance as dictation.
[Plans and limits](/help/plans-and-limits) has the detail.
* **Local and self-hosted processing don't touch it.** If your meetings are
transcribed by on-device models or your own server, no words are counted
against a cloud allowance at all. You can set that per-feature on the
**Note Recording** tab — see
[record a meeting](/help/meetings/record-a-meeting).
* **Speaker labels cost nothing extra.** They run locally on your machine on
every plan — see [speaker labels](/help/meetings/speaker-labels).
* **Syncing meeting notes between devices needs a paid plan**, like all note
sync — see [sync across devices](/help/notes/sync-across-devices).
## If something doesn't look right
If you think you're being limited when you shouldn't be, or a limit message
doesn't match the plan you're on, don't work around it — tell us and we'll look
at the account:
* [Weekly limit reached, but I'm on a paid plan](/help/fix/paid-but-shows-free)
* ["Daily Limit Reached" doesn't match what I expected](/help/fix/daily-limit-message)
## Related
* [Plans and limits](/help/plans-and-limits)
* [Is OpenWhispr free?](/help/account/is-openwhispr-free)
* [Record a meeting](/help/meetings/record-a-meeting)
# Record a meeting
Source: https://docs.openwhispr.com/help/meetings/record-a-meeting
Start a meeting note by hand or from a prompt, watch it transcribe live, and find it afterwards.
A meeting note records the call, transcribes it as people talk, and saves the
whole thing as a note you can search later. You can start one from the prompt
OpenWhispr shows you, or start it yourself at any time.
## Start one yourself
Press your **Meeting Mode Hotkey**. That opens meeting mode and begins a note
straight away — useful when the prompt didn't appear, or when you're recording
something that isn't a call at all, like a lecture or an interview.
To set or change that shortcut, open **Settings**, then **Hotkeys** under
**App**, and look for **Meeting Mode Hotkey**. The same panel has a
**When triggered by hotkey, open in:** choice — **Full width** or
**Side panel** — which decides how the meeting view appears when you use the
shortcut.
## Start one from the prompt
When OpenWhispr thinks a meeting has started, a card appears asking whether you
want to take notes. Choose **Take notes** and recording begins.
If the prompt came from a calendar event with a meeting link, the button reads
**Join & transcribe** instead — that opens the meeting and starts the note in
one go.
The card is drawn by OpenWhispr rather than your operating system, so it still
reaches you when Do Not Disturb or Focus is on. It's also excluded from screen
capture, so it won't show up in a share or a recording.
[How meeting detection decides](/help/meetings/how-meeting-detection-works)
covers what triggers that prompt and how to turn it off.
## While it's recording
Text appears as people speak. A pill sits at the top of the transcript with the
recording controls, and if OpenWhispr is still waiting on your microphone it
says so — **Waiting for microphone** — rather than failing quietly.
Speaker labels are assigned live and tidied up once the call ends, so don't
worry if they look rough mid-meeting. The app tells you as much:
*"Still identifying speakers. Labeling accuracy will improve once the call
ends."* See [speaker labels](/help/meetings/speaker-labels).
Recording your own microphone is not the same as recording the people on the
call. Capturing the other side needs a system-audio permission, and on some
setups it needs a bit more than that — see
[capturing both sides of the call](/help/meetings/capture-both-sides).
## Where the note ends up
Meeting notes are saved into your **Meetings** folder automatically. If the
prompt came from a calendar event, the note takes that event's title; otherwise
it starts as **New note** and you can rename it.
From there it behaves like any other note — editable, searchable, and available
to the AI actions that clean up or summarise it.
## Choosing how meetings get transcribed
Meeting recording keeps its **own** engine setting, separate from dictation.
Open **Settings**, then **Speech-to-Text** under **AI Models**, and pick the
**Note Recording** tab. Four options:
| Mode | What it means |
| -------------------- | ------------------------------------------------------ |
| **OpenWhispr Cloud** | Reliable accuracy, no setup. Needs you to be signed in |
| **Cloud Providers** | Bring your own API key |
| **Local** | On-device models, fully private |
| **Self-Hosted** | Your own server on your network |
Changing this tab changes meetings only. Your dictation engine and your audio
upload engine are set on their own tabs and are unaffected.
## Related
* [How meeting detection works](/help/meetings/how-meeting-detection-works)
* [Speaker labels](/help/meetings/speaker-labels)
* [Capturing both sides of the call](/help/meetings/capture-both-sides)
* [Connect Google Calendar](/help/meetings/connect-google-calendar)
* [Meeting audio isn't being captured](/help/fix/meeting-audio-not-captured)
# Speaker labels
Source: https://docs.openwhispr.com/help/meetings/speaker-labels
How OpenWhispr works out who said what, how to correct it, and how to turn it off for a recording.
In a meeting note, OpenWhispr separates the voices and labels who said what.
Labels appear live and are refined once the call ends, so the finished transcript
is more accurate than what you watch scroll past.
## Where the work happens
Speaker identification runs **on your own machine**. The models it needs — a
segmentation model and a voice-embedding model — download automatically the
first time you use the feature, and everything after that is local.
That matters for two reasons: it keeps working when the call audio never leaves
your device, and it means the labels aren't a cloud feature you're waiting on.
[Where your data goes](/help/privacy/where-your-data-goes) has the full picture.
## Turning it on or off for good
The master switch is **Identify and label speakers**, and it's on by default.
Open **Settings**, then **Speech-to-Text** under **AI Models**, and pick the
**Note Recording** tab — the toggle sits underneath the four engine options.
Switch it off and transcripts show "You" and "Others" instead of named speakers,
as the setting itself says.
It's on the **Note Recording** tab specifically, alongside the engine used for
meetings — not in a section of its own. If you're looking for a "Meetings"
section in Settings, there isn't one.
## Controls during a recording
You can also override the setting for a single meeting without changing it
globally. The pill at the top of the transcript carries the controls:
| Control | What it does |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Speaker identification toggle** | Turns labelling off for **this recording only**. The transcript falls back to "You" and "Them", split by whether the audio came from your microphone or from the call |
| **Expected speaker count** | A stepper reading *"1 other in call"*. Nudge it up when more people join |
The count is a hint, not a limit you have to get right. When the note came from a
calendar event, the attendee list pre-fills it. OpenWhispr supports up to **8**
speakers in a recording and starts from an assumption of **2**.
Getting the count roughly right genuinely helps. Setting it far too high is how
you end up with phantom speakers — one person split across three labels.
## Naming people
Labels start as **Speaker 1**, **Speaker 2** and so on. Click one and type a
name to replace it. If the meeting came from a calendar event, its attendees are
offered as suggestions, and people you've named before appear under **Known
speakers**.
Once you name someone, that voice can carry the same name into later meetings
rather than starting from scratch each time.
Labels also carry a state, which tells you how much to trust them:
| State | Meaning |
| --------------- | -------------------------------------------------- |
| **Provisional** | Assigned live, still subject to change |
| **Suggested** | OpenWhispr thinks it knows who this is |
| **Confirmed** | You named it |
| **Locked** | Fixed, and won't be reassigned by later processing |
## Fixing a wrong label
Select the mislabelled segments and assign the right person. You can select
several at once — the toolbar shows *"3 selected"* with an **Assign to…**
action, which is much faster than correcting line by line.
Corrections you make are treated as confirmed, so post-processing won't undo
them.
## If the labels look wrong mid-call
Give it until the end. Live labelling works from a fraction of the audio; the
refinement pass at the end of the call sees the whole recording and regroups the
voices properly. The app says so itself while recording: *"Still identifying
speakers. Labeling accuracy will improve once the call ends."*
Things that genuinely hurt accuracy, in rough order:
1. **Everyone on one microphone in a room.** Voices sharing a channel are the
hardest case there is.
2. **A speaker count set far from reality.**
3. **Heavy crosstalk.** People talking over each other blurs the boundaries.
4. **Only capturing your own microphone.** If the other side was never recorded,
there's nothing to label — see
[capturing both sides of the call](/help/meetings/capture-both-sides).
## Turning it off
Two levels, depending on what you want:
| Scope | Where |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **Every recording** | **Settings** → **Speech-to-Text** → **Note Recording** tab → **Identify and label speakers** |
| **This recording only** | The toggle on the recording pill |
Either way the transcript still captures everything — it just labels by source,
"You" for your microphone and "Them" for the call, instead of by voice.
There's no separate cost to leaving speaker labels on, and no plan tier to
reach first — the models run locally on your machine.
## Related
* [Record a meeting](/help/meetings/record-a-meeting)
* [Capturing both sides of the call](/help/meetings/capture-both-sides)
* [Where your data goes](/help/privacy/where-your-data-goes)
# Export your notes
Source: https://docs.openwhispr.com/help/notes/export-your-notes
Save a single note as Markdown, or keep every note mirrored to a folder on disk automatically.
Two ways to get your notes out of OpenWhispr: export one when you need it, or
have every note written to disk continuously.
## Exporting one note
Open the note and use **Export** in the editor. Two choices:
| Option | What you get |
| --------------------- | --------------- |
| **As Markdown** | The note itself |
| **As Markdown (.md)** | The transcript |
For a meeting note those are different documents — the note is what you and the
AI actions made of it, the transcript is what was said.
## Keeping every note on disk
**Save notes as files** mirrors your notes to a folder automatically, as
Markdown, organised by folder — so `Work > Meeting Notes` becomes
`Work/Meeting Notes.md` on disk.
Open **Settings**, then **Preferences** under **App**, and find
**Save notes as files**:
| Control | What it does |
| --------------------------------------- | ------------------------------------------------ |
| The toggle | Turns the mirroring on |
| **Save location** / **Change location** | Where the files go |
| **Rebuild all files** | Re-writes every note and transcript from scratch |
**Rebuild all files** is the one to reach for after moving the folder, or if the
files on disk have drifted from what's in the app.
This is how to use OpenWhispr with a Markdown tool like Obsidian: point the
save location at your vault (or a folder inside it) and your notes appear
there as ordinary `.md` files. There's no Obsidian-specific integration — the
files are plain Markdown, which is what makes them work anywhere.
OpenWhispr **owns** that directory. It rewrites each file whole when a note
changes, and deleting a folder in the app deletes it on disk. Don't hand-edit
the files or keep anything else in there — point the save location at a folder
used for nothing else, and edit notes in the app.
## Formats
Export is **Markdown**. There's no built-in DOCX or PDF export today — if you
need one of those, export the Markdown and convert it, or paste into the
application you're producing the document in.
If that's blocking something for you, [tell us](/help/getting-help) — knowing
what people actually need is how it gets prioritised.
## Taking everything with you
If you're leaving, or want a full copy of your data rather than your notes:
* **Save notes as files** with **Rebuild all files** gives you every note as
Markdown in one pass.
* A **full export of your account data** can be requested from
[support@openwhispr.com](mailto:support@openwhispr.com) — see
[GDPR and your data rights](/help/privacy/gdpr-and-your-data-rights).
## Related
* [Organise notes with folders](/help/notes/organise-with-folders)
* [Sync notes across devices](/help/notes/sync-across-devices)
* [GDPR and your data rights](/help/privacy/gdpr-and-your-data-rights)
# Organise notes with folders
Source: https://docs.openwhispr.com/help/notes/organise-with-folders
Create folders, move notes between them, and understand the folders OpenWhispr makes for you.
Every note lives in a folder, and folders live inside a space. Your **Personal**
space is private to you; if your team uses team spaces, those appear separately.
## Creating and using folders
Create a folder from the sidebar, then drag notes into it. A note can be moved
between folders freely, and folders can be renamed whenever you like.
Two rules worth knowing before you reorganise:
* **Default folders can't be changed or deleted.** OpenWhispr creates a few for
itself — **Meetings** is where meeting recordings land, and audio fetched from
a URL goes to **Videos**. The app will tell you: *"Default folders cannot be
changed."*
* **Folder names must be unique** within their space. A repeat gives you
*"A folder with that name already exists."*
## Where things get filed automatically
| What you did | Where it lands |
| ---------------------------- | ----------------------- |
| Recorded a meeting | **Meetings** |
| Pasted a URL to transcribe | **Videos** |
| Dictated, or uploaded a file | Wherever you're working |
## Folders inside a team space
If you're a member of a team space, its folders sit under **Team spaces** in the
sidebar, separately from your private ones.
Moving a note or folder **into** a team space is a one-way trip. Everyone in
that space can then view and edit it, and it can't be moved back out — the app
warns you before you confirm, and says plainly afterwards:
*"Notes can't be moved out of a team space."*
Move a copy rather than the original if you want to keep a private version.
Two more constraints in shared spaces:
* Only the note's **owner** or a **workspace admin** can move it to another
space.
* Deleting a team space deletes its folders and notes **for everyone**, and
you'll be asked to type the space's name to confirm.
[Team spaces](/guides/team-spaces) covers roles and membership.
## Mirroring folders to disk
If you'd like your folder structure to exist as real files on your computer,
turn on **Save notes as files** — it writes each note as Markdown, organised by
folder, to a location you choose. See
[export your notes](/help/notes/export-your-notes).
## Related
* [Search your notes](/help/notes/search-your-notes)
* [Export your notes](/help/notes/export-your-notes)
* [Share a note](/help/notes/share-a-note)
* [Team spaces](/guides/team-spaces)
# Search your notes
Source: https://docs.openwhispr.com/help/notes/search-your-notes
Find a note by the words in it or by what it was about, including transcripts of past meetings.
Search covers everything you've saved — dictations, meeting transcripts,
uploads and notes you typed yourself.
## Searching
Use the search box above your notes list, or **Search notes** in the sidebar,
and type. Results narrow as you go; when nothing matches you'll get
*"No notes found for …"* rather than an empty screen.
## Two ways of matching
OpenWhispr searches in two ways at once, which is why a search sometimes finds
the right note even when your words aren't in it:
| Kind | Finds |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Keyword search** | Notes containing the words you typed |
| **Meaning-based search** | Notes about the same thing, even in different words — searching *"budget disagreement"* can surface a note that says *"we couldn't agree on the numbers"* |
Both run on your own machine. Meaning-based search works from an index
OpenWhispr builds locally as notes are saved.
## Searching a meeting
Meeting transcripts are searchable like any other note, so a name or a phrase
from a call three weeks ago is a search away. If you named the speakers, their
names are part of the text and searchable too — see
[speaker labels](/help/meetings/speaker-labels).
## Asking rather than searching
When you're not looking for a *note* but for an *answer*, the chat agent
searches your notes for you and answers from what it finds — useful for
questions like "what did we decide about pricing?" that span several notes.
Each note also has its own chat panel, scoped to just that note.
See [the chat agent](/help/agent/chat-agent).
## If a note doesn't turn up
1. **Check which space you're in.** Notes in a team space are listed separately
from your personal ones.
2. **Check it was saved at all.** With **Data Retention** turned off,
dictations are pasted but never stored — see
[what we store](/help/privacy/what-we-store-and-for-how-long).
3. **Try a phrase from the middle of it** rather than the title. Titles are
often auto-generated and may not say what you remember.
4. **If a dictation went missing rather than a note**, there's a specific
recovery path — see
[recover a lost dictation](/help/fix/recover-a-lost-dictation).
## Related
* [Organise notes with folders](/help/notes/organise-with-folders)
* [The chat agent](/help/agent/chat-agent)
* [Recover a lost dictation](/help/fix/recover-a-lost-dictation)
# Share a note
Source: https://docs.openwhispr.com/help/notes/share-a-note
Send someone a link or invite them by email, choose who can see it, and take access away again.
Sharing publishes a single note so other people can read — or edit — it. It's a
per-note decision: nothing is shared until you share it.
Sharing notes requires a **paid plan**. On the Free plan the dialog will tell
you: *"Sharing notes requires a paid plan."*
## Sharing one
Open the note and choose **Share**.
If the note has never been synced, you'll be asked to sync it first —
*"Sharing keeps a copy of this note in your OpenWhispr cloud. Only you can see
it until you choose who to share it with."* Choose **Sync note** to continue.
That's unavoidable: a note that exists only on your laptop can't be opened by
anyone else.
Then either:
* **Invite people by email** — type an address and send. They get an invitation,
shown as **Pending** until they accept and **Has access** afterwards.
* **Create link** — produces a URL you can paste anywhere, governed by the
visibility setting below.
## Who can see it
**Visibility** has four settings:
| Setting | Who gets in |
| ----------------------------------------- | ----------------------------------------------------------------- |
| **Private — only you** | Nobody else. The starting state |
| **Only people invited** | The people you invited by email, and nobody else |
| **Everyone at your domain with the link** | Anyone with the link whose email is on your organisation's domain |
| **Anyone with the link** | Anyone at all who has the URL |
**Anyone with the link** means anyone — links get forwarded, pasted into
tickets, and indexed if they end up somewhere public. For anything sensitive,
use **Only people invited**, which ties access to an identity you chose rather
than to knowledge of a URL.
## What people can do
Each person you invite is either:
* **Can view** — read only
* **Can edit** — read and change the note
The **Owner** is you, and that doesn't transfer.
## Taking access away
In the same dialog, use **Remove** on a person to revoke their access, or set
**Visibility** back to **Private — only you** to close it off entirely. You can
also **Resend invite** if someone never received theirs — there's a short
cool-down, so if you hit *"Invitation sent recently. Try again in a minute,"*
that's what it is.
Shared notes keep syncing to the cloud even if you later turn **Cloud backup**
off — sharing is its own consent. To stop that, unshare the note. See
[sync across devices](/help/notes/sync-across-devices).
## Sharing with a whole team instead
If you're repeatedly sharing notes with the same people, a **team space** is the
better instrument — everyone in the space sees its folders and notes without
per-note invitations. See [Team spaces](/guides/team-spaces) and
[organise notes with folders](/help/notes/organise-with-folders) for the
one-way-move rule that comes with it.
## Related
* [Sync notes across devices](/help/notes/sync-across-devices)
* [Team spaces](/guides/team-spaces)
* [Where your data goes](/help/privacy/where-your-data-goes)
# Sync notes across devices
Source: https://docs.openwhispr.com/help/notes/sync-across-devices
Turn on cloud backup, what syncs and what doesn't, and why shared notes behave differently.
OpenWhispr is local-first: your notes live on the machine you made them on, and
that copy stays the source of truth. Syncing adds a cloud copy so your other
devices can see the same notes.
It's **off by default**. Nothing leaves your machine until you turn it on.
## Turning it on
Open **Settings**, then **Privacy & Data** under **System**, and switch on
**Cloud backup**.
Three things all have to be true for notes to sync:
1. You're **signed in** to an OpenWhispr account
2. **Cloud backup** is on
3. You're on a **paid plan**
Sync is a paid feature — on the Free plan the toggle won't produce syncing even
when you're signed in. See [plans and limits](/help/plans-and-limits).
When you first switch it on, existing notes are uploaded in the background and
the app reports progress — *"Backing up notes… 12 / 40"*, then
*"All notes backed up"*. The section also shows **Last synced** so you can tell
at a glance whether it's current.
## Two exceptions that sync anyway
Shared notes and team-space content keep syncing **even with cloud backup off**,
as long as you're signed in on a paid plan. The app states this next to the
toggle: *"Notes in team spaces and notes you've shared always sync, regardless
of this setting."*
The logic is that each of those is its own act of consent. You can't share a
note with someone and also require it never leave your device, and a team space
is shared by definition. If you want something to stay local, keep it in your
personal space and don't share it.
## What happens with the same note on two machines
Edits are reconciled by which came last. Open a note on your laptop, edit it on
your desktop, and the newer version wins.
The practical advice is ordinary: let a device finish syncing before editing the
same note somewhere else. **Last synced** tells you where things stand.
## Turning it off
Switch **Cloud backup** off. Local notes stay exactly where they are — the
setting controls the cloud copy, not your own.
To remove what's already been uploaded, or to remove everything, see
[what we store, and for how long](/help/privacy/what-we-store-and-for-how-long)
and [delete your account](/help/account/delete-your-account).
## Related
* [What OpenWhispr stores, and for how long](/help/privacy/what-we-store-and-for-how-long)
* [Share a note](/help/notes/share-a-note)
* [Plans and limits](/help/plans-and-limits)
* [Export your notes](/help/notes/export-your-notes)
# Plans and limits
Source: https://docs.openwhispr.com/help/plans-and-limits
What each plan includes, the exact limits that apply, and what happens when you reach one.
Every limit on this page is the limit the product actually enforces. If you hit
something that isn't listed here, that's a bug in this page — please
[tell us](mailto:support@openwhispr.com).
## The plans
| | Free | Pro | Business | Enterprise |
| ------------------------------ | ------------------------------ | ---------------------- | ---------------------------------- | ---------- |
| Price | \$0 | \$8/month or \$80/year | \$20/user/month or \$200/user/year | Custom |
| OpenWhispr Cloud transcription | 2,000 words per rolling 7 days | Unlimited | Unlimited | Unlimited |
| Local AI models | Unlimited | Unlimited | Unlimited | Unlimited |
| Your own API keys (BYOK) | Unlimited | Unlimited | Unlimited | Unlimited |
| Meeting recordings | 5 hours/month | 20 hours/month | Unlimited | Unlimited |
| Languages | 100+ | 100+ | 100+ | 100+ |
| Support | Community | Email | Priority | Dedicated |
No card is needed to start. You only add payment details if you upgrade.
## The cloud word limit
The Free plan includes **2,000 words per rolling 7 days** of OpenWhispr Cloud
transcription. Free forever — it isn't a trial and it doesn't expire.
Three things worth knowing, because they're the ones people write in about:
**It's a rolling window, not a weekly reset.** There's no Monday when the
counter goes back to zero. Instead, each transcription stops counting once it's
more than 7 days old. So if you used your 2,000 words last Tuesday, they free up
again this Tuesday.
**Only OpenWhispr Cloud counts.** Local models and your own API keys are
unlimited on every plan, and neither touches this number. If you're regularly
hitting the limit and don't want to upgrade, switching to a local model removes
it entirely — see [Cloud vs local processing](/guides/cloud-vs-local).
**We don't cut you off mid-transcription.** The check happens when a
transcription starts, so a single long recording can carry you past 2,000 words
rather than stopping halfway. You'll be over your limit afterwards, not left
with half a transcript.
You can see where you stand in **Settings → Account**.
## Audio file size limits
These apply when you upload a file or paste a URL in the **Upload** view. They
depend on how you're processing audio, not just on your plan:
| How you're processing | Maximum file size |
| -------------------------------------------- | ----------------- |
| Local models (whisper.cpp, Parakeet) | No limit |
| Self-hosted or custom endpoint | No limit |
| Your own API key (BYOK) | 25 MB |
| OpenWhispr Cloud — Free | 25 MB |
| OpenWhispr Cloud — Pro, Business, Enterprise | 500 MB |
A 45-minute MP3 recorded at a typical bitrate is usually **40–65 MB**, so it
will exceed the 25 MB limit on the Free plan and with your own API keys. A
45-minute recording is comfortably within the 500 MB limit on a paid plan.
If a file is too large, OpenWhispr tells you before it uploads anything — you
won't lose a long upload to a limit you didn't know about.
**URL downloads** — YouTube links and direct audio or video URLs — are capped at
500 MB, and the same processing limits above then apply to the downloaded file.
**Using the REST API or the CLI directly?** Every request to the transcription
endpoint is capped at **25 MB, on every plan**. The 500 MB figure above is the
desktop app's limit: it splits large files into smaller pieces and reassembles
the result for you. If you're calling the API yourself, split the audio your
side. See the [API overview](/api/overview).
## Meeting recordings
Meeting recording allowances are 5 hours a month on Free, 20 hours a month on
Pro, and unlimited on Business and Enterprise.
Meeting audio processed with a local model or your own API key doesn't use
OpenWhispr Cloud, so it doesn't count toward the cloud word limit above.
## Languages
OpenWhispr supports 100+ languages. Which ones are available depends on the
model you're using — the local Parakeet models cover a smaller set than Whisper
does. You can pick a language or leave it on auto-detect; see
[How dictation works](/guides/dictation).
## Changing or cancelling your plan
You can upgrade, downgrade or cancel at any time. If you cancel, you keep
unlimited local dictation on the Free plan — on-device transcription never stops
working.
To cancel or ask about a refund, email
[support@openwhispr.com](mailto:support@openwhispr.com) and we'll take care of
it.
# Answering a security review
Source: https://docs.openwhispr.com/help/privacy/for-your-it-team
Everything an IT or security team usually asks about OpenWhispr, in one place — with the documents to attach.
This is the page to send when someone asks you to justify OpenWhispr to your
security team. It collects the answers and the documents in one place, so you're
not assembling them from five tabs.
If something here doesn't cover what your reviewer asked, email
[support@openwhispr.com](mailto:support@openwhispr.com) — we answer security
questionnaires.
## The documents
| Document | Where |
| ----------------------------------------------------------- | ---------------------------------------------------------- |
| Data Processing Addendum, including the sub-processor annex | [openwhispr.com/dpa](https://openwhispr.com/dpa) |
| Privacy Policy | [openwhispr.com/privacy](https://openwhispr.com/privacy) |
| Security overview | [openwhispr.com/security](https://openwhispr.com/security) |
| Terms of Service | [openwhispr.com/terms](https://openwhispr.com/terms) |
| Trust centre — live controls and sub-processors | [trust.openwhispr.com](https://trust.openwhispr.com) |
| SOC 2 Type 2 report | Under NDA, once issued — ask support@ |
## What the product does with data
OpenWhispr records audio when a user presses a hotkey, turns it into text, and
puts that text at their cursor. Where the audio goes depends entirely on the
speech-to-text mode:
| Mode | Audio destination | Our cloud involved? |
| ------------------ | ------------------------------ | ------------------- |
| Local | The device | No |
| Self-Hosted | Your own server | No |
| Bring your own key | The provider you contract with | No |
| OpenWhispr Cloud | Our API, then a model provider | Yes |
On OpenWhispr Cloud we store the **transcript text** and technical metadata. We
do not store audio — it's processed in the request and discarded. [Where your
voice and text go](/help/privacy/where-your-data-goes) has the detail, including
the fact that custom-dictionary terms travel with cloud requests.
Managed Enterprise Bedrock and Azure OpenAI apply to AI text features such as
cleanup, agent, note chat, formatting, and translation. Those prompts go
directly from the device to the customer's cloud account. Audio still follows
the speech-to-text mode selected for dictation, note recording, or upload.
**Data residency:** the United States, for us and our sub-processors. Transfers
out of the EEA, UK and Switzerland run on adequacy where it exists and the
Standard Contractual Clauses otherwise.
**AI training:** OpenWhispr does not use customer content for training, and
providers contracted by OpenWhispr are held to the same restriction under
[Section 3 of the DPA](https://openwhispr.com/dpa). Customer-owned BYOK and
Enterprise cloud accounts are governed by the customer's provider agreement and
account configuration.
## Network
* **Outbound only, TLS on 443.** Everything else it runs binds to your own
machine by design.
* **System proxies and PAC scripts are honoured**, on all three platforms.
* **Allowlist by hostname, not IP** — provider addresses change without notice.
* The full host list, split by what's required and what's optional, is in
[network allowlist](/help/it/network-allowlist). That's the page to hand a
firewall administrator.
## Endpoint security
* Managed enterprise credentials are short-lived and remain in the desktop main
process. AWS credentials last up to 15 minutes; Microsoft sets the Azure token
expiry. They are cleared when the employee signs out or changes workspace.
* Manually entered API keys are encrypted through the OS keychain — Keychain,
DPAPI, libsecret — and never sent to us.
* On Linux with no keyring available, Electron falls back to plaintext. Make sure
a keyring is installed and unlocked on managed Linux fleets. [How OpenWhispr is
secured](/help/privacy/how-openwhispr-is-secured) explains the constraint.
* Local history is an ordinary SQLite file in the user's application-data folder,
protected by the OS account and full-disk encryption rather than by a second
layer of our own.
* The app auto-updates from GitHub release artifacts.
## Retention
Retention is set per device, and users can reach it under **Settings** →
**Privacy & Data** under **System**. Defaults: audio deleted after **30 days**,
transcripts kept until deleted, history **on**, cloud backup **off**.
If your policy is "nothing on disk", the setting to turn off is **Data
Retention** — text is still pasted, nothing is saved. See [what OpenWhispr stores,
and for how long](/help/privacy/what-we-store-and-for-how-long).
## Central administration
Active Enterprise workspace owners can configure these controls in the
OpenWhispr admin portal. Business and Pro workspaces keep ordinary sign-in and
manual provider setup.
* SAML or OIDC company sign-in and verified-domain SSO enforcement
* SCIM 2.0 user lifecycle and group-to-team provisioning
* centrally managed Amazon Bedrock or Azure OpenAI access with no employee keys
* provider allowlists, retention, sharing, cloud backup, and minimum app version
Managed enterprise AI uses a five-minute, workspace-scoped OpenWhispr assertion
to obtain temporary credentials from the customer's cloud. Prompts and responses
continue directly between the desktop and that cloud account; OpenWhispr is not
the model proxy.
Start with [SCIM provisioning](/help/it/scim-provisioning), then configure
[managed Amazon Bedrock or Azure OpenAI](/help/it/managed-enterprise-ai).
## Compliance posture
Stated precisely, because reviewers check:
* **SOC 2 Type 2** — audit complete, observation period passed, final report
available under NDA once issued.
* **HIPAA** and **GDPR** — attestations held (2026, through our compliance
platform). A BAA (available on the Business plan and above) is required
before any PHI goes through the cloud service; see
[HIPAA and healthcare use](/help/privacy/hipaa-and-healthcare).
* **ISO 27001:2022** — programme aligned, all 93 Annex A controls implemented,
certification audit not yet undertaken.
## Reporting a vulnerability
[security@openwhispr.com](mailto:security@openwhispr.com), or GitHub's private
vulnerability reporting. Not a public issue, please.
## Related
* [Network allowlist](/help/it/network-allowlist)
* [SCIM provisioning](/help/it/scim-provisioning)
* [Managed enterprise AI](/help/it/managed-enterprise-ai)
* [How OpenWhispr is secured](/help/privacy/how-openwhispr-is-secured)
* [GDPR and your data rights](/help/privacy/gdpr-and-your-data-rights)
* [HIPAA and healthcare use](/help/privacy/hipaa-and-healthcare)
* [Enterprise providers](/guides/enterprise)
# GDPR and your data rights
Source: https://docs.openwhispr.com/help/privacy/gdpr-and-your-data-rights
What rights you have over your data, how to exercise each one, and what business customers need for their own compliance.
You can get a copy of your data, correct it, delete it, or tell us to stop
processing it. Some of that you can do yourself in the app; the rest is one email
away.
Email [support@openwhispr.com](mailto:support@openwhispr.com) for any request you
can't complete in the app. A person handles it — there's no form to find.
## Your rights and how to use each one
| Right | How |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Access** — a copy of what we hold | Email [support@openwhispr.com](mailto:support@openwhispr.com) and we'll put a full export together |
| **Portability** — your content in a usable format | Export your notes as Markdown yourself ([saving notes as files](/guides/notes)), or ask us for a full export |
| **Correction** | [Change your email address](/help/account/change-your-email) yourself, or ask us for anything else |
| **Erasure** | [Delete your account](/help/account/delete-your-account) in the app, or ask us |
| **Restriction and objection** | Email [support@openwhispr.com](mailto:support@openwhispr.com) |
| **Complaint** | You can lodge one with your supervisory authority at any time |
Deleting individual notes, clearing your local history, and turning off cloud
features are all things you can do yourself — see [what OpenWhispr stores, and
for how long](/help/privacy/what-we-store-and-for-how-long).
## Getting a full export
You can export your notes yourself as Markdown, mirroring your folder structure.
For **everything we hold** — notes, transcription history and account data
together — email [support@openwhispr.com](mailto:support@openwhispr.com) and ask
for a full export. We'll put it together and send it to the address on the
account.
A formal request doesn't need special wording. Say what you want in plain
language and we'll treat it as the request it is. Tell us the email address on
the account so we can find it.
## Where your data is processed
OpenWhispr is operated from the **United States**, and we and our sub-processors
process personal data primarily there. For transfers out of the EEA, the UK and
Switzerland, our [DPA](https://openwhispr.com/dpa) applies the first mechanism
that fits: an adequacy decision where the destination has one, and otherwise the
**Standard Contractual Clauses** — Module Two, controller to processor — with the
UK Addendum for UK data and the Swiss adaptations for Swiss data.
If you'd rather your content never left your machine at all, local and
self-hosted modes are the answer: [where your voice and text
go](/help/privacy/where-your-data-goes) explains the difference.
## Training
Your content is never used to train AI models, and our providers are contractually
held to the same. That's [its own article](/help/privacy/is-my-data-used-to-train-ai)
because it's the question we're asked most.
## If you're a business customer
For your own GDPR compliance you'll usually need three things, and all three are
published:
* **The DPA** — [openwhispr.com/dpa](https://openwhispr.com/dpa). It's incorporated
into our terms, so it already applies. If your legal team needs it signed as a
counterpart, email [support@openwhispr.com](mailto:support@openwhispr.com).
* **The sub-processor list** — Annex 3 of the DPA, with the live version on our
[trust centre](https://trust.openwhispr.com).
* **Our security controls** — summarised in [how OpenWhispr is
secured](/help/privacy/how-openwhispr-is-secured), with the full set on the trust
centre.
We hold a GDPR attestation (2026, through our compliance platform). [Answering a
security review](/help/privacy/for-your-it-team) collects everything a vendor
assessment tends to ask for.
## FAQ
We aim to deal with it well inside the one-month period the GDPR allows, and
usually much sooner. If a request is complex we'll tell you.
No. Deleting the account is the fastest complete route, but you can ask us to
erase specific data instead. If you want to stop paying without losing
anything, [cancelling](/help/account/cancel-your-subscription) is a different
thing again.
Both, depending on the data. For content you put through the product we act as
a processor on your behalf. For your account and billing data we're the
controller. The [DPA](https://openwhispr.com/dpa) sets out the split.
Californian users have the right to know what's collected, to request
deletion, and to opt out of sale. We don't sell personal information. The
[Privacy Policy](https://openwhispr.com/privacy) covers it.
## Related
* [Deleting your account](/help/account/delete-your-account)
* [What OpenWhispr stores, and for how long](/help/privacy/what-we-store-and-for-how-long)
* [Answering a security review](/help/privacy/for-your-it-team)
* [Privacy Policy](https://openwhispr.com/privacy) · [DPA](https://openwhispr.com/dpa)
# HIPAA and healthcare use
Source: https://docs.openwhispr.com/help/privacy/hipaa-and-healthcare
Where OpenWhispr stands on HIPAA, when you need a BAA, and which processing modes keep PHI out of our cloud entirely.
If you're a Covered Entity or a Business Associate and you want to dictate
anything containing protected health information, the rule is short: **get a BAA
in place first.** Email [support@openwhispr.com](mailto:support@openwhispr.com)
and we'll start it.
Without a signed BAA, PHI must not go through the cloud service. That's not
fine print we're hiding — it's [Section 14 of our DPA](https://openwhispr.com/dpa),
and it exists to protect you as much as us.
## Where we stand
| | Status |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HIPAA attestation** | Held (2026, through our compliance platform) |
| **Our role** | Business Associate — we process ePHI on your behalf, we're not a Covered Entity |
| **BAA** | Offered on request on the Business plan and above. Required before any PHI goes through the cloud service |
| **Sub-processor BAAs** | Executed with the sub-processors that store content — our database and cloud transcription and language-model providers. Coverage of the remaining HIPAA-path sub-processors is in progress |
We've written that last row the way it actually is rather than rounding it up.
If you need the current state of a specific sub-processor before you sign, ask
and we'll tell you where it stands.
## Getting a BAA
The BAA is available on the Business plan and above. From a Business or
Enterprise account, email [support@openwhispr.com](mailto:support@openwhispr.com)
with your organisation's name and who should sign; if you're on Free or Pro,
upgrade first. Once it's executed, the BAA governs PHI in place of the DPA
wherever the two would conflict.
Do this before your team starts dictating clinical content, not after.
## Keeping PHI out of our cloud altogether
Some organisations would rather not send PHI to a vendor at all, whatever the
paperwork says. Four of OpenWhispr's five processing modes make that possible,
because our cloud isn't in the path:
| Mode | Where the audio goes |
| ---------------------- | ------------------------------------------------- |
| **Local** | Nowhere — transcribed on the device |
| **Self-Hosted** | Your own server on your network |
| **Bring your own key** | Direct to the provider you hold the contract with |
| **Enterprise** | Your organisation's own cloud account |
Local mode is the strongest position: the audio never leaves the machine, and it
works offline once the model is downloaded. Set it per activity — dictation, note
recording and audio upload each have their own engine setting under **Settings**
→ **Speech-to-Text** under **AI Models**. [Where your voice and text
go](/help/privacy/where-your-data-goes) explains why all three matter.
Switching **Dictation** to local does not move **Audio Upload** off the cloud.
They're separate settings on separate tabs. If you're standing up a
PHI-safe configuration, check all three tabs and confirm each one.
If you're evaluating a clinical-grade option under your own contract, **Corti**
is available as a bring-your-own-key provider — clinical transcription with
EU-hosted cleanup and reasoning. See [cloud vs local
processing](/guides/cloud-vs-local).
## FAQ
HIPAA compliance is a property of how an organisation uses a tool, not a badge
a product carries on its own. What we can tell you: we hold a HIPAA
attestation, we act as a Business Associate, and we sign a BAA before any PHI
is processed. With that BAA in place and an appropriate configuration, you can
use OpenWhispr in a HIPAA-regulated workflow.
If PHI never reaches our servers, we're not processing it and there's nothing
for a BAA to cover. That said, most compliance teams still want the agreement
on file in case someone switches a mode later. Ask us for one.
No. The BAA is available on the Business plan and above. If you're on Free
or Pro and need one, upgrade first — then ask and we'll go through it with
you.
They're kept locally under your retention settings, 30 days by default, and
you can turn audio retention off entirely. That's part of your own HIPAA
footprint, so it's worth setting deliberately — see [what OpenWhispr stores,
and for how long](/help/privacy/what-we-store-and-for-how-long).
## Related
* [How OpenWhispr is secured](/help/privacy/how-openwhispr-is-secured)
* [Answering a security review](/help/privacy/for-your-it-team)
* [Where your voice and text go](/help/privacy/where-your-data-goes)
* [Data Processing Addendum](https://openwhispr.com/dpa)
# How OpenWhispr is secured
Source: https://docs.openwhispr.com/help/privacy/how-openwhispr-is-secured
Encryption, credential storage, access control, and where our compliance attestations actually stand.
Short version: everything in transit is encrypted with TLS, data at rest in our
cloud database is encrypted, your API keys are held in your operating system's
own keychain, and everything the desktop app runs binds to your own machine by
design.
The binding detail lives in our [security
overview](https://openwhispr.com/security) and the [DPA](https://openwhispr.com/dpa).
Our [trust centre](https://trust.openwhispr.com) carries the live control list
and the current sub-processors.
## Encryption
| Where | What protects it |
| ---------------------------------- | ------------------------------------------------------------------- |
| **In transit** | TLS 1.2 or higher on every connection, to us and to model providers |
| **At rest, our cloud** | Encrypted at the database layer |
| **At rest, your machine** | Your OS account and your disk encryption — FileVault, BitLocker |
| **Your manually entered API keys** | Encrypted through your OS keychain |
| **Managed cloud credentials** | Short-lived and held in desktop memory only |
## How your API keys are stored
Keys you enter — bring-your-own-key credentials and manually configured enterprise credentials
— are encrypted using Electron's `safeStorage`, which hands off to the operating
system's own secret store: **Keychain** on macOS, **DPAPI** on Windows,
**libsecret** on Linux. The encrypted blobs sit in a `secure-keys` folder inside
OpenWhispr's application data.
They are never sent to OpenWhispr's servers.
**One real limitation, on Linux.** If your system has no keyring available,
Electron falls back to storing secrets in plaintext. That's Electron's default
behaviour rather than something we've chosen, but the effect is the same: on a
Linux box without a working keyring, treat stored API keys as unprotected at
rest. Install and unlock a keyring — GNOME Keyring, KWallet — before entering
keys on a shared or portable machine.
## Managed enterprise identity
Managed Amazon Bedrock and Azure OpenAI access does not put a permanent cloud
secret on the employee's device. After a company SSO login, OpenWhispr issues a
five-minute assertion scoped to one workspace and one provider. AWS STS exchanges
it for credentials requested for 15 minutes, or Microsoft Entra exchanges it for
an Azure token with a Microsoft-controlled expiry.
Those credentials stay in the Electron main process. They are not sent to the
page interface, written to disk, or returned by desktop IPC. Signing out,
switching accounts, or changing workspaces clears the cache.
The assertion endpoint verifies the current SSO session, workspace membership,
SCIM assignment when enforced, subscription, and provider policy before signing.
AWS and Microsoft validate the workspace-specific issuer, audience, subject, and
signature against OpenWhispr's public JWKS.
## The desktop app
* **Loopback-only by design, with one known exception.** Every connection to
our servers is outbound and client-initiated, over TLS on port 443. A few
components listen on `127.0.0.1` for the app's own local pieces to talk to
each other — the CLI bridge, an auth bridge, an OAuth callback catcher, and
local model servers when you use them. The bundled Parakeet speech server is
the one exception: its upstream binary can't bind loopback-only, so on
Windows it listens on all interfaces until the installer's firewall rule
closes it off — see [antivirus and firewall
prompts](/help/fix/antivirus-blocks-openwhispr) for what that means for
per-user and portable installs.
* **Context isolation is on**, with a restricted preload bridge between the app's
interface and the parts of it that can reach your system.
* **Native helpers are compiled from source** during our build — the key listener
and paste utilities aren't downloaded binaries.
## Access and monitoring on our side
Production access is least-privilege and requires MFA. Access and sessions are
logged and monitored, with logins reviewed monthly. We run vulnerability and
patch management alongside secure development practices, and staff are under
confidentiality obligations with security training.
Backups and recovery objectives are documented — a four-hour recovery time
objective and a one-hour recovery point objective for the primary datastore —
and the contingency plan is tested annually.
## Where our compliance stands
We'd rather be precise here than impressive, because this is exactly the sort of
claim that gets checked.
| | Status |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **SOC 2 Type 2** | Audit complete and the observation period has passed. The final report is available under NDA once issued |
| **HIPAA** | Attestation held (2026, through our compliance platform) — see [HIPAA and healthcare use](/help/privacy/hipaa-and-healthcare) |
| **GDPR** | Attestation held (2026, through our compliance platform) — see [GDPR and your data rights](/help/privacy/gdpr-and-your-data-rights) |
| **ISO 27001:2022** | Our programme is aligned to it and all 93 Annex A controls are implemented. We have **not** undertaken a certification audit |
If you need the SOC 2 report or a completed security questionnaire, email
[support@openwhispr.com](mailto:support@openwhispr.com) and say which you need.
## Reporting a security issue
Email [security@openwhispr.com](mailto:security@openwhispr.com), or use [GitHub's
private vulnerability
reporting](https://github.com/OpenWhispr/openwhispr/security/advisories/new).
Please don't open a public issue for a security problem. We aim to acknowledge
within 48 hours.
## Related
* [Answering a security review](/help/privacy/for-your-it-team)
* [Where your voice and text go](/help/privacy/where-your-data-goes)
* [Network allowlist](/help/it/network-allowlist)
* [SCIM provisioning](/help/it/scim-provisioning)
* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Security overview](https://openwhispr.com/security)
# Is my data used to train AI models?
Source: https://docs.openwhispr.com/help/privacy/is-my-data-used-to-train-ai
No. What that covers, what our providers are contractually held to, and what it means for bring-your-own-key setups.
**OpenWhispr does not use your content for AI training.** The same restriction
applies to providers OpenWhispr contracts to deliver the cloud service.
That isn't just a stated intention. It's a binding commitment in our [Data
Processing Addendum](https://openwhispr.com/dpa), Section 3, and it survives the
end of your contract with us.
## What it covers
Everything you put through the product:
* the audio you record
* the transcripts that come back
* your notes
* prompts and conversations with the AI agent
## What our providers are held to
OpenWhispr uses third-party providers to run transcription and language models.
They're bound by the same restriction: they process your content solely to
deliver the service, with model training disabled or opted out on our accounts,
and they're not permitted to train on it. The current list is published in Annex
3 of the [DPA](https://openwhispr.com/dpa) and kept live on our [trust
centre](https://trust.openwhispr.com).
## If you use your own cloud account
Bring-your-own-key requests go directly from your machine to the provider whose
credentials you entered. Managed Enterprise AI sends text prompts directly to
your organization's Bedrock or Azure OpenAI account; transcription audio follows
its separately selected speech-to-text mode. OpenWhispr isn't in those direct
provider paths, so **your provider agreement and account configuration** govern
training there.
Most providers disable training on paid API traffic by default, but it's your
account and your agreement with them. If training policy is the reason you chose
BYOK, check the terms on the key you're using.
Local and self-hosted modes avoid the question entirely: nothing leaves your
machine or your network.
## FAQ
No. Cloud backup stores your notes so you can reach them from another device.
It doesn't make them training data.
Not as a matter of course. Support can only see what you send us in a ticket.
Access to production systems is restricted, logged, and reviewed — see [how
OpenWhispr is secured](/help/privacy/how-openwhispr-is-secured).
Yes — the DPA is the document to send, and Section 3 is the clause. [Answering
a security review](/help/privacy/for-your-it-team) lists everything else
reviewers usually ask for.
## Related
* [Where your voice and text go](/help/privacy/where-your-data-goes)
* [Answering a security review](/help/privacy/for-your-it-team)
* [Data Processing Addendum](https://openwhispr.com/dpa)
# What OpenWhispr stores, and for how long
Source: https://docs.openwhispr.com/help/privacy/what-we-store-and-for-how-long
The retention settings, what they default to, where your data sits on disk, and how to delete it.
Most of what OpenWhispr keeps is on **your own machine**, and you control how
long it stays there. Two settings do the work: audio recordings are deleted after
**30 days** by default, and transcripts are kept **forever** by default until you
change it.
Both live in one place. Open **Settings**, then **Privacy & Data** under
**System**.
## The settings, and what they're set to out of the box
| Setting | Default | What it does |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| **Data Retention** | On | Saves transcriptions and audio to your history. Turn it off and text is still pasted, just never saved |
| **Audio Retention** | 30 days | Deletes stored recordings after this long |
| **Transcript Retention** | Forever | Deletes saved transcriptions — and their audio — after this long |
| **Save discarded dictations** | Off | Keeps the audio of dictations you cancelled with Escape, so you can recover them |
| **Cloud backup** | Off | Backs your notes and transcriptions up to the cloud |
Audio Retention and Transcript Retention both offer 1, 7, 14, 30, 60 or 90 days.
Audio Retention can also be set to **Disabled**, which keeps no audio at all;
Transcript Retention can be set to **Forever**, which is where it starts.
**Save discarded dictations** needs both Data Retention and Audio Retention
switched on — it has nowhere to keep the audio otherwise. The app says as much
under the toggle.
## Turning history off entirely
Set **Data Retention** off. Your words are still typed at your cursor; nothing is
written to history. The app confirms this state in the history view: *"Data
retention is off. Transcriptions and audio are not saved to history."*
This is the setting to reach for if you dictate anything you'd rather not have
sitting on disk afterwards.
## Deleting what's already there
The same section has a **Storage Usage** panel showing how many audio files are
stored and how much space they take, with a **Clear All Audio** button beneath
it. It deletes every stored recording and can't be undone.
Shortening a retention period also applies to what you've already got — the
next cleanup sweep removes anything past the new limit.
## Where it sits on disk
If you'd rather look for yourself, or you're wiping a machine:
| Platform | Folder |
| ----------- | ------------------------------------------ |
| **macOS** | `~/Library/Application Support/OpenWhispr` |
| **Windows** | `%APPDATA%\OpenWhispr` |
| **Linux** | `~/.config/OpenWhispr` |
Inside it, `audio/` holds the recordings and `transcriptions.db` is the SQLite
database holding your history.
That database is an ordinary file on your computer — OpenWhispr doesn't encrypt
it separately. It's protected by your operating system account and by whatever
full-disk encryption you have on, such as FileVault or BitLocker. Your saved API
keys are the exception: those are encrypted through your OS keychain, described
in [how OpenWhispr is secured](/help/privacy/how-openwhispr-is-secured).
## What we hold on our side
If a mode is on OpenWhispr Cloud, we store the **transcript text** and its
technical metadata — provider, model, language, duration, timings. We don't store
the audio, and we don't store voice-agent
[screen context](/help/agent/voice-agent) screenshots — they're passed to the
model for that one request and never retained.
[Where your voice and text go](/help/privacy/where-your-data-goes) covers this
in detail.
If **Cloud backup** is on, your notes are backed up to your account as well.
All of it goes when your account does. [Deleting your
account](/help/account/delete-your-account) sets out exactly what's removed, and
it's also the route for a formal erasure request.
## FAQ
Yes. The limit applies to everything stored, not just new recordings, so
lowering it clears out anything already past the new period.
No. It stops new transcriptions being saved; what's already there stays until
you delete it or a retention period expires. **Clear All Audio** removes the
recordings.
If cloud backup is on, deleting locally removes it from your backup too. Notes
in a team space belong to that space — see [team
spaces](/guides/team-spaces).
## Related
* [Where your voice and text go](/help/privacy/where-your-data-goes)
* [Deleting your account](/help/account/delete-your-account)
* [Recovering a cancelled dictation](/help/fix/recover-a-lost-dictation)
* [GDPR and your data rights](/help/privacy/gdpr-and-your-data-rights)
# Where your voice and text go
Source: https://docs.openwhispr.com/help/privacy/where-your-data-goes
What leaves your device when you dictate, what reaches OpenWhispr's servers, and what never goes anywhere — per processing mode.
It depends on which **processing mode** you're on, and nothing else. On local
mode, your audio never leaves your machine. On OpenWhispr Cloud, it's sent to us,
transcribed, and the audio is discarded — we keep the text, not the recording.
The important part is that the mode is set **per activity**, not once for the
whole app.
## The mode is set three times, not once
Dictation, note recording and audio upload each have their own engine setting.
They're independent, so it's normal to be on local for dictation and on cloud for
uploads without realising it.
Open **Settings**, choose **Speech-to-Text** under **AI Models**, and you'll see
three tabs:
| Tab | Covers |
| ------------------ | --------------------------- |
| **Dictation** | Press-to-talk dictation |
| **Note Recording** | Meeting and note recordings |
| **Audio Upload** | Files and URLs you upload |
Check all three if you care where a particular kind of audio goes. Changing one
does nothing to the other two.
## What each mode does with your audio
| Mode | Where the audio goes | What OpenWhispr keeps |
| ---------------------- | ---------------------------------------------- | ---------------------------------- |
| **Local** | Nowhere — transcribed on your device | Nothing |
| **Self-Hosted** | Your own server on your network | Nothing |
| **OpenWhispr Cloud** | Our servers, then the model provider | The transcript text, not the audio |
| **Bring your own key** | Straight to the provider whose key you entered | Nothing |
On local and self-hosted mode, OpenWhispr Cloud isn't in the path at all. On
bring-your-own-key, the request goes from your machine to the provider you
configured — we don't proxy it and we don't see it. Our
[DPA](https://openwhispr.com/dpa) puts this in legal terms: in those modes the
providers act on your instructions, not as our sub-processors.
### Managed enterprise identity is separate from the model request
With centrally managed Amazon Bedrock or Azure OpenAI, the desktop contacts the
OpenWhispr API first to fetch non-secret workspace configuration and request a
short-lived identity assertion. That request contains account, workspace,
provider, and policy context — not the prompt, audio, transcript, or model
response.
The desktop exchanges the assertion with AWS STS or Microsoft Entra, then sends
the actual AI text prompt directly to the configured customer cloud endpoint.
Temporary cloud credentials stay in desktop memory and are cleared when the
account or workspace changes. This controls cleanup, agent, note chat,
formatting, and translation; transcription audio still follows whichever of the
three speech-to-text tabs you selected above.
## What travels with a cloud request
When a mode is on OpenWhispr Cloud, the request carries four things:
* the **audio** itself
* the **model** you're transcribing with
* your **transcription language**, if you've set one rather than using auto-detect
* your **custom dictionary** terms, if you use one — they're sent as a prompt so
the model spells names and jargon correctly
That last one surprises people, so it's worth stating plainly: if you've added
client names or internal project names to your dictionary, those words go with
every cloud transcription request. If that's not acceptable for your setup, keep
the dictionary empty and use local or self-hosted mode.
**Screen context is the one case where an image is sent.** If you turn on
[**Share screen context**](/help/agent/voice-agent) — it's off unless you do —
then pressing the voice agent hotkey also sends a screenshot of the display your
cursor is on, to whichever model that scope is pointed at. It's used for that
single request and nothing else: never written to disk, never added to your
notes or transcription history, and never included in logs. Ordinary dictation
never sends one.
## What we store when you use the cloud
The transcript and its technical metadata — the text, its word count, which
provider and model ran it, the language, how long the audio was, how long
processing took, and the timestamp.
**Not the audio.** OpenWhispr has no audio storage: recordings are processed in
the request and discarded, which is also what our
[DPA](https://openwhispr.com/dpa) commits to. The provider that runs the model
handles the audio transiently under its own agreement with us.
Audio *is* kept on your own machine if you leave audio retention on — that's a
local setting, not a cloud one, and it's covered in [what OpenWhispr stores and
for how long](/help/privacy/what-we-store-and-for-how-long).
## Notes and cloud backup
Your notes and transcription history live on your device by default. **Cloud
backup is off** unless you turn it on.
To change it, open **Settings**, then **Privacy & Data** under **System**, and
use the **Cloud backup** toggle.
One exception, and the app says so too: notes in team spaces and notes you've
shared always sync, whatever the cloud backup setting says. Sharing a note is
what puts it in the cloud.
## Usage analytics
There's a **Usage analytics** toggle in the same place, and it's **off by
default**. Leave it off and nothing about your usage is sent.
## Related
* [Cloud vs local processing](/guides/cloud-vs-local)
* [What OpenWhispr stores, and for how long](/help/privacy/what-we-store-and-for-how-long)
* [Is my data used to train AI models?](/help/privacy/is-my-data-used-to-train-ai)
* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Privacy Policy](https://openwhispr.com/privacy)
# Introduction
Source: https://docs.openwhispr.com/index
OpenWhispr is an open-source voice-to-text dictation app with AI agents, meeting transcription, and notes. Available on macOS, Windows, and Linux.
OpenWhispr turns your voice into text, notes, and actions. It runs on your desktop with local or cloud speech recognition, an AI agent you can talk to, live meeting transcription, and a full notes system with semantic search.
## What you can do
Press a hotkey, speak, and your words appear at your cursor. Works in any app.
Talk to your AI assistant using OpenAI, Anthropic, Google, or local models.
Auto-detect Zoom, Teams, and FaceTime calls. Transcribe with speaker labels.
Create, organize, and search notes with folders, cloud sync, and AI actions.
Shared spaces for your workspace's notes, with access granted by teams.
## Processing options
Choose how your audio is processed:
* **OpenWhispr Cloud** — sign in and transcribe instantly, no API keys needed
* **Bring your own key** — use your own OpenAI, Groq, xAI, Mistral, Tinfoil, OpenRouter, or Corti credentials
* **Local processing** — download Whisper, NVIDIA Parakeet, or Nemotron models for completely private transcription
## Platforms
OpenWhispr runs on macOS 12+, Windows 10+, and 64-bit Linux. Download from the [releases page](https://github.com/OpenWhispr/openwhispr/releases/latest) or build from source. [System requirements](/platform/system-requirements) has the detail, including what on-device models need.
Apple Silicon and Intel
x64 with push-to-talk
AppImage, deb, rpm, tar.gz
## For developers
OpenWhispr has a public REST API and an MCP server for AI assistant integration.
Manage notes, folders, transcriptions, and usage programmatically.
Connect Claude, Cursor, or VS Code to your OpenWhispr data.
# Agent setup
Source: https://docs.openwhispr.com/integrations/agent-setup
Let your AI assistant create its own API key in under 30 seconds.
AI assistants like Claude, Cursor, and VS Code can create their own OpenWhispr API key without opening the desktop app. The entire flow happens via API — the only human step is pasting a 6-digit code.
## How it works
The agent sends your email to the API:
```bash theme={null}
curl -X POST https://api.openwhispr.com/api/v1/auth/email-code \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com"}'
```
You'll receive a 6-digit code by email.
Paste the code when the agent asks for it:
```bash theme={null}
curl -X POST https://api.openwhispr.com/api/v1/auth/email-code/verify \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "code": "482901"}'
```
Returns a short-lived session token (valid for 15 minutes):
```json theme={null}
{
"data": {
"token": "owt_...",
"expires_at": "2026-04-16T12:15:00Z"
}
}
```
The agent uses the session token to create a permanent key:
```bash theme={null}
curl -X POST https://api.openwhispr.com/api/v1/keys/create \
-H "Authorization: Bearer owt_..." \
-H "Content-Type: application/json" \
-d '{"name": "Claude Code - MacBook Pro", "scopes": ["notes:read", "notes:write"]}'
```
Returns:
```json theme={null}
{
"data": {
"key": "owk_live_...",
"id": "...",
"name": "Claude Code - MacBook Pro",
"scopes": ["notes:read", "notes:write"],
"expires_at": null,
"created_at": "2026-04-16T12:00:00Z"
}
}
```
The agent stores the `owk_live_` key and uses it for all future requests — same as a key created in the desktop app.
## Rate limits
* **1 code per 60 seconds** per email
* **5 codes per hour** per email
* **10 codes per hour** per IP
* **5 attempts per code** before it's locked
* Codes expire after **10 minutes**
* Session tokens expire after **15 minutes**
## Managing keys via the API
Once authenticated with a session token or desktop session, you can manage keys:
| Endpoint | Method | Description |
| -------------------------- | ------ | -------------------- |
| `/api/v1/keys/create` | POST | Create a new API key |
| `/api/v1/keys/list` | GET | List active API keys |
| `/api/v1/keys/{id}/revoke` | POST | Revoke an API key |
See [API keys](/integrations/api-keys) for scope details and limits.
## Security
* The verification code is **hashed server-side** — it's never stored in plain text
* Session tokens have a **15-minute TTL** and can only manage API keys (not read notes)
* The token prefix `owt_` distinguishes session tokens from `owk_live_` API keys
* Requesting a code for a non-existent email returns the same response to prevent enumeration
# API keys
Source: https://docs.openwhispr.com/integrations/api-keys
Create and manage API keys for the OpenWhispr API and MCP server.
API keys authenticate requests to the [REST API](/api/overview) and the [MCP server](/integrations/mcp).
## Creating a key
1. Open the OpenWhispr desktop app
2. Click **Integrations** in the left sidebar
3. On the **API** card, click **Manage keys**
4. Click **Create API Key**, give it a name, and tick the permissions you need
5. Choose an expiry — **Never expires**, 30, 60 or 90 days, or 1 year
6. Copy the key — it starts with `owk_live_` and is only shown once
Key management is offered on paid plans.
### What the app can grant
The dialog offers three permissions:
| Checkbox | Scope |
| ------------------- | --------------------- |
| Read notes | `notes:read` |
| Create & edit notes | `notes:write` |
| Read transcriptions | `transcriptions:read` |
Every key also gets `usage:read`, which isn't shown as a checkbox and isn't
listed on the key afterwards.
`transcriptions:delete` is the one scope the app can't grant — there's no checkbox for it, so a key made in the desktop app can't delete transcriptions. To get one, create the key [through the API](/integrations/agent-setup) and name the scope explicitly.
Store your key securely. If you lose it, revoke it and create a new one.
### Creating keys via the API
AI assistants can create their own keys programmatically using the [agent setup flow](/integrations/agent-setup). You can also manage keys via the API:
* `POST /api/v1/keys/create` — create a new key
* `GET /api/v1/keys/list` — list active keys
* `POST /api/v1/keys/{id}/revoke` — revoke a key
These endpoints accept both desktop session auth and agent session tokens (`owt_` prefix).
**Known discrepancy:** the published [OpenAPI
contract](/api-reference/keys/list-api-keys) for `GET /api/v1/keys/list`
returns `{ "data": [...] }` — an array directly under `data`. The current
desktop app's key-management client code expects
`{ "data": { "keys": [...] } }` instead. Until this is reconciled, don't
assume either shape — inspect the actual response before building an
integration against it.
## Scopes
Each key has specific permissions. Choose only what you need.
| Scope | Access |
| ----------------------- | ----------------------------------------------------------------- |
| `notes:read` | List, get, and search notes. Read note transcripts. List folders. |
| `notes:write` | Create, update, and delete notes. Create folders. |
| `transcriptions:read` | List and get transcription history. |
| `transcriptions:delete` | Delete a transcription and its audio. |
| `usage:read` | Read usage statistics and plan details. |
Team spaces use a separate kind of key with its own scopes — see [Workspace API keys](/api/workspace-keys).
## Limits
* Max **5 API keys** per user (workspace keys are counted separately — **20** per workspace)
* Expiry is chosen at creation: never, 30, 60 or 90 days, or 1 year
* Keys can be **revoked** at any time from the desktop app
## Key format
```
owk_live_
```
Keys are 32 bytes of cryptographic randomness, prefixed with `owk_live_` for identification. Only the SHA-256 hash is stored server-side — the raw key cannot be recovered after creation.
## Best practices
* Use separate keys for different integrations so you can revoke one without affecting others
* Set expiration dates for keys used in temporary automations
* Use the minimum scopes needed — a read-only dashboard doesn't need `notes:write`
# MCP server
Source: https://docs.openwhispr.com/integrations/mcp
Connect your AI assistant to OpenWhispr using the Model Context Protocol.
The OpenWhispr MCP server lets AI assistants like Claude, Cursor, and VS Code access your notes, folders, transcriptions, and usage stats directly.
It's hosted at `https://mcp.openwhispr.com/mcp` and uses the Streamable HTTP transport — no local install needed.
## Setup
You'll need a personal [API key](/integrations/api-keys) (`owk_live_`) with the scopes you want the assistant to access. The MCP server reaches your own notes, so workspace keys aren't supported here.
AI assistants can create their own API key automatically — see [Agent setup](/integrations/agent-setup).
```bash theme={null}
claude mcp add openwhispr --transport http https://mcp.openwhispr.com/mcp \
--header "Authorization: Bearer owk_live_YOUR_KEY"
```
Go to **Settings > Integrations > Add MCP Server** and enter:
* **URL:** `https://mcp.openwhispr.com/mcp`
* **Authorization:** `Bearer owk_live_YOUR_KEY`
Add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"openwhispr": {
"url": "https://mcp.openwhispr.com/mcp",
"headers": {
"Authorization": "Bearer owk_live_YOUR_KEY"
}
}
}
}
```
Add to `.vscode/mcp.json` in your workspace, or run **MCP: Open User
Configuration** from the Command Palette for a config that follows you
across projects:
```json theme={null}
{
"servers": {
"openwhispr": {
"type": "http",
"url": "https://mcp.openwhispr.com/mcp",
"headers": {
"Authorization": "Bearer ${input:openwhispr_api_key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "openwhispr_api_key",
"description": "OpenWhispr API key",
"password": true
}
]
}
```
VS Code prompts for the key once and stores it securely instead of
writing it into the config file. See the [VS Code MCP server
reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
for the full schema.
## Available tools
Once connected, your assistant has access to these tools:
| Tool | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| `list_notes` | List notes with optional folder filtering and pagination |
| `get_note` | Get a single note by ID |
| `create_note` | Create a new note |
| `update_note` | Update a note's title, content, or folder |
| `delete_note` | Delete a note |
| `search_notes` | Semantic and full-text search across notes |
| `list_folders` | List all folders |
| `create_folder` | Create a new folder |
| `list_transcriptions` | List transcription history with filtering by language or note |
| `get_transcription` | Get a transcription by ID, including speaker-attributed segments with timestamps |
| `get_note_transcript` | Get the transcript for a specific note with structured segments |
| `get_usage` | Get usage stats, word counts, and plan details |
## Required scopes
Create the API key with only the scopes you need.
| Scope | Tools |
| --------------------- | ------------------------------------------------------------------------------- |
| `notes:read` | `list_notes`, `get_note`, `search_notes`, `list_folders`, `get_note_transcript` |
| `notes:write` | `create_note`, `update_note`, `delete_note`, `create_folder` |
| `transcriptions:read` | `list_transcriptions`, `get_transcription` |
| `usage:read` | `get_usage` |
## Example prompts
Try these after connecting:
* "Show me my recent notes"
* "Search my notes for the meeting with the design team"
* "Create a note titled 'Project Ideas' in my Work folder"
* "How many words have I used this month?"
* "List my transcriptions from today"
* "Get the transcript from my last meeting note as subtitles"
* "Show the transcript for note \[id] with speaker segments"
## How it works
The MCP server is a thin wrapper around the [OpenWhispr API](/api/overview). Your API key is passed through on every request — the MCP server doesn't store credentials or session state.
Each request creates a fresh, stateless connection. This means it scales horizontally and works with any MCP client that supports Streamable HTTP transport.
# Dictating into other apps
Source: https://docs.openwhispr.com/platform/dictating-into-other-apps
How your words get from OpenWhispr into whatever you're typing in — and what to do when they don't.
OpenWhispr works in any application that accepts typed text: your email client,
a chat window, a document, a code editor, a browser form. There's no list of
supported apps to check, because it isn't integrating with them — it's putting
text where your cursor already is.
Knowing *how* it does that explains every case where it doesn't.
## What actually happens
When you finish dictating, OpenWhispr:
1. Copies the finished text to your clipboard.
2. Sends the paste keystroke to whichever window has focus.
3. Puts your previous clipboard contents back a moment later.
That's it. Nothing is typed character by character, and nothing is injected into
the other application.
Two consequences worth knowing:
* **Your clipboard is borrowed, not taken.** It's restored afterwards — unless
it changed in the meantime, in which case OpenWhispr leaves the newer contents
alone rather than overwriting something you copied.
* **Focus decides everything.** The text lands wherever the cursor is when
dictation finishes. Click into the target field before you stop speaking, not
after.
## The two settings
Both are under **Settings** → **Preferences** under **App**, in the
**Clipboard** group:
| Setting | Default | What it does |
| ----------------------------------- | ------- | --------------------------------------------------------------------------------- |
| **Automatic pasting** | On | Pastes the text into the active app when dictation finishes |
| **Keep transcription in clipboard** | Off | Leaves the dictation on your clipboard instead of restoring what was there before |
Turn automatic pasting off and OpenWhispr becomes copy-only: dictate, then paste
where you like. Some people prefer that in apps where they want to review before
committing.
## What each platform needs
| Platform | Requirement |
| ----------- | ---------------------------------------------------------------------------------------------- |
| **macOS** | Accessibility permission. Without it, text is copied but not pasted |
| **Windows** | Nothing — it works out of the box |
| **Linux** | A paste tool or `/dev/uinput` access, depending on your session — see [Linux](/platform/linux) |
## When the paste doesn't land
The transcription worked and the paste didn't. Press
Cmd/Ctrl+V — the text is on your clipboard,
which is the deliberate fallback for every failure in this path. Then see
[the text doesn't paste](/help/fix/text-not-pasting) for the cause.
Whatever had focus when dictation ended received the text. This most often
happens when a notification or another app steals focus mid-dictation.
A known issue with a specific cause on Windows rather than something about
the app you were in. [The text pasted
twice](/help/fix/text-pasted-twice) has it.
Terminals use a different paste shortcut, and OpenWhispr switches to it when
it recognises one. [Editors, IDEs and
terminals](/platform/editors-and-terminals) covers what it recognises and
what to do when yours isn't on the list.
That's the voice agent, not the paste path. [It answers instead of
typing](/help/fix/it-answers-instead-of-typing) explains the trigger and how
to turn it off.
## Fields that refuse pasted text
Some secure entry fields reject text that arrives from a paste, whatever is
doing the pasting. That's the other application's decision, not something
OpenWhispr can work around — and not something we'd want to. The transcription
stays on your clipboard either way.
## Related
* [Editors, IDEs and terminals](/platform/editors-and-terminals)
* [Automatic pasting and your clipboard](/help/dictation/auto-paste-and-clipboard)
* [The text doesn't paste](/help/fix/text-not-pasting)
# Editors, IDEs and terminals
Source: https://docs.openwhispr.com/platform/editors-and-terminals
Why terminals need a different paste shortcut, which ones OpenWhispr recognises, and what to do when yours isn't recognised.
Dictating into a code editor is the same as dictating into anything else.
Terminals are the exception, and the reason is a keyboard shortcut rather than
anything about OpenWhispr.
## Why terminals are different
Ctrl+V means "paste" almost everywhere. In a terminal it
has meant something else since long before graphical desktops, so terminals
moved paste onto Ctrl+Shift+V. Send the wrong
one and you get nothing, or a control character.
So OpenWhispr looks at the window that has focus and picks the shortcut to
match. You don't configure this.
## What gets recognised
By window class: **Windows Terminal**, the classic console host (**Command
Prompt** and **PowerShell**), **ConEmu**, **mintty** (Git Bash),
**PuTTY**, **Alacritty**, **WezTerm**, **kitty**, **Hyper**, **MobaXterm**.
Electron-based terminals all share one window class, so they're recognised
by their executable instead: **Termius**, **Tabby**, **Wave**, **Rio**.
Around two dozen, by window class or process name: **Konsole**,
**GNOME Terminal**, **kitty**, **Alacritty**, **Terminator**, **xterm**,
**urxvt**, **rxvt**, **Tilix**, **Terminology**, **WezTerm**, **foot**,
**st**, **Yakuake**, **Ghostty**, **Guake**, **Tilda**, **Hyper**,
**Tabby**, **sakura**, **Warp**, **Termius**, **WaveTerm**.
macOS doesn't need the distinction — Cmd+V pastes in
Terminal, iTerm2 and everywhere else, so OpenWhispr sends the same
keystroke throughout.
## Editors that contain terminals
VS Code, Cursor and other Electron-based editors are a special case on Linux:
they're a normal window that may or may not have a terminal panel focused
inside it, and there's no way to tell from outside.
OpenWhispr sends Shift+Insert to them instead. It's the
one shortcut that pastes correctly in both the editor and an embedded terminal,
and — unlike Ctrl+V — terminal AI agents such as Claude
Code, Codex and OpenCode don't intercept it as "paste image".
**Konsole** gets the same treatment on any desktop: it silently drops a
simulated Ctrl+Shift+V, a long-standing quirk
of how it handles simulated input.
On Linux, OpenWhispr also mirrors the text into the X11 **primary selection**,
which is what Shift+Insert pastes from in most terminals.
That's why the fallback works even where the clipboard path doesn't.
## If your terminal isn't recognised
You'll see one of two things: nothing pasted, or the text appearing somewhere
unexpected.
The text is on your clipboard.
Ctrl+Shift+V puts it in.
Recognition is a list of names, so adding yours is a small change. Email
[support@openwhispr.com](mailto:support@openwhispr.com) with the terminal's
name and your operating system.
**Settings** → **Preferences** under **App** → **Clipboard** →
**Automatic pasting**. Dictation still transcribes; you paste where you
want it.
## Dictating code
Worth setting expectations: transcription models are trained on speech, not on
source code. Function names, symbols and punctuation-heavy syntax come out
approximately at best.
What works well is the prose around code — commit messages, pull-request
descriptions, comments, documentation, and prompts to a terminal AI agent.
Those are also where most people find the time saving.
The [custom dictionary](/help/customise/custom-dictionary) helps with the
vocabulary that matters to you: library names, your own product names, the
acronyms your team uses.
## Related
* [Dictating into other apps](/platform/dictating-into-other-apps)
* [The text doesn't paste](/help/fix/text-not-pasting)
* [Linux](/platform/linux)
# Linux
Source: https://docs.openwhispr.com/platform/linux
Which package to install, what changes between X11 and Wayland, and the desktop-specific behaviour for hotkeys, pasting and system audio.
OpenWhispr runs on 64-bit Linux and works on every desktop we've tried, but
more of its behaviour depends on your session here than it does on macOS or
Windows. This page is the map of what changes and why.
## What you need
* 64-bit **x86-64** — there's no ARM build
* **PulseAudio or PipeWire** for audio; PipeWire is also what system-audio
capture uses
## Which package to install
| Format | For | Sign-in with Google, Apple or Microsoft |
| ----------- | ------------------------------ | --------------------------------------- |
| `.deb` | Debian, Ubuntu, Mint, Pop!\_OS | Yes |
| `.rpm` | Fedora, RHEL, openSUSE | Yes |
| `.AppImage` | Anything, no install | **Email sign-in only** |
| `.tar.gz` | Anything, manual | **Email sign-in only** |
**This is the one choice worth making deliberately.** Browser sign-in works by
registering the `openwhispr://` URL scheme, and only the packaged installs do
that. On AppImage and tar.gz the Google, Apple and Microsoft buttons are
disabled with the message *"Browser sign-in unavailable"*. Signing in with an
email code still works, and everything after sign-in behaves identically.
```bash theme={null}
sudo apt install ./OpenWhispr-*-linux-x64.deb
```
```bash theme={null}
sudo dnf install ./OpenWhispr-*-linux-x64.rpm
```
```bash theme={null}
chmod +x OpenWhispr-*.AppImage
./OpenWhispr-*.AppImage
```
```bash theme={null}
tar -xzf OpenWhispr-*-linux-x64.tar.gz
cd OpenWhispr-*/
./openwhispr
```
## Pasting into other apps
OpenWhispr always copies your transcription to the clipboard. Putting it into
the focused window is the part that depends on your session.
It ships a native paste helper and uses it where it can. On **X11** that's the
normal case and needs nothing from you. On **Wayland** the helper needs access
to `/dev/uinput`, which most distributions don't grant by default:
```bash theme={null}
sudo usermod -aG input $USER
```
Log out and back in afterwards — group membership isn't picked up until you do.
Where the helper can't be used, OpenWhispr falls back to whichever tool you have
installed:
| Session | Tool it looks for |
| -------------------------------------------- | ---------------------------------------------------------------------------- |
| X11 | `xdotool` |
| Sway, Hyprland and other wlroots compositors | `wtype`, then `xdotool` for XWayland apps |
| GNOME, KDE and other Wayland sessions | `xdotool` for XWayland apps, or `ydotool` with the `ydotoold` daemon running |
If none of them is available the app tells you plainly — *"Clipboard Mode on
Wayland"* — and you paste with Ctrl+V yourself. That's a
designed fallback, not a failure.
[Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio) is
the step-by-step version, including which packages to install.
### Terminals and editors
Terminals take Ctrl+Shift+V rather than
Ctrl+V, and OpenWhispr recognises around two dozen of
them. Konsole and Electron-based editors like VS Code and Cursor get
Shift+Insert instead, because that's the one that works
reliably in both. [Editors, IDEs and
terminals](/platform/editors-and-terminals) explains when that matters.
## Hotkeys
The default dictation hotkey is Ctrl+Super.
Electron's own global shortcuts don't work on Wayland, so OpenWhispr registers
through the desktop environment instead — and which one you run changes what's
possible:
Shortcuts are registered as native GNOME custom shortcuts over D-Bus and
gsettings, so they show up under **Settings → Keyboard → Shortcuts →
Custom**. GNOME reports a shortcut as a single press, so **hold-to-talk
isn't available** through this path.
Shortcuts are registered through KDE's own global shortcut service over
D-Bus, one shortcut per action.
Bindings are applied with `hyprctl` at runtime and re-applied each time
OpenWhispr starts. If the app can't write to your Hyprland config it says
so — the binding works for this session but won't survive a config reload.
OpenWhispr also claims the combination, so an existing Hyprland bind on the
same keys is unbound.
Most desktops reserve a long list of combinations, particularly anything built
on Super. OpenWhispr refuses those with a reason rather than binding
something that silently never fires. [Choosing a shortcut that
works](/help/dictation/choosing-a-shortcut) covers the rules.
**Hold-to-talk** needs the same `input` group membership as the paste helper.
Until that's in place dictation runs in tap mode, and the app shows **Hold to
Speak needs setup** with the command to run.
## System audio for meetings
System audio is captured through **PipeWire**, from your default sink monitor.
There's no permission dialog and no screen-share picker on Linux — if you were
expecting one, its absence is correct.
Check that the audio you want is playing through the default sink before you
start recording. [Meeting audio isn't
captured](/help/fix/meeting-audio-not-captured) covers the rest.
## What isn't available on Linux
* **Launch at login** — the setting is hidden rather than shown and ignored.
Use your desktop's own autostart, pointed at the OpenWhispr binary or its
`.desktop` entry.
* **The Globe key and mouse-button hotkeys** — macOS only.
## Updates and uninstalling
Update the way you installed: fetch the new package and install it over the
top, or replace the AppImage. Settings, history and downloaded models are kept.
Uninstalling a `.deb` or `.rpm` removes cached models as part of the package's
own cleanup. For other formats, remove `~/.cache/openwhispr/` yourself. Adding
`~/.config/OpenWhispr` gives you a clean slate — and takes your local settings,
history and un-synced notes with it.
## Related
* [System requirements](/platform/system-requirements)
* [Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio)
* [Where your files live](/platform/where-your-files-live)
* [Hold or tap](/help/dictation/hold-or-tap)
# macOS
Source: https://docs.openwhispr.com/platform/macos
Installing on a Mac, the three permissions macOS asks for, the Globe key, and how updates work.
OpenWhispr on macOS is a menu-bar app. It runs quietly in the background, waits
for your hotkey, and types into whatever you're working in.
## What you need
* **macOS 12 (Monterey) or later**
* **Apple Silicon or Intel** — separate downloads, described below
* **macOS 14.2 or later** if you want to record system audio in meetings
## Installing
There are two `.dmg` files on the [releases
page](https://github.com/OpenWhispr/openwhispr/releases/latest) — one for
**Apple Silicon**, one for **Intel**. Apple menu → **About This Mac** tells
you which you have.
Open the disk image and drag OpenWhispr into your Applications folder.
Running it from the mounted disk image instead causes odd behaviour later,
so do move it across.
The app is signed and notarised by Gizmo Labs Inc., so macOS opens it
without a security warning. Onboarding asks for the permissions below.
Installed the Intel build on an Apple Silicon Mac? You don't need to do
anything — OpenWhispr detects that it's running under Rosetta and switches
you to the Apple Silicon build at the next update.
## Permissions
macOS makes you grant these explicitly, and dictation is only partly useful
until you do. They live in the app under **Settings** → **Privacy & Data**
under **System** → **Permissions**. Each card shows a **Grant Access** button
until it's granted — once it is, the card turns green with a checkmark and the
button disappears.
| Permission | What stops working without it | Where macOS keeps it |
| -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Microphone** | Everything — no audio is captured | System Settings → Privacy & Security → Microphone |
| **Accessibility** | Automatic pasting. Text still reaches your clipboard, so you can paste it yourself | System Settings → Privacy & Security → Accessibility |
| **System Audio** | Recording other participants in a meeting. Your own voice is still captured | System Settings → Privacy & Security → Screen Recording |
| **Screen Recording** | [Screen context](/help/agent/voice-agent) for the voice agent, which is off by default | System Settings → Privacy & Security → Screen Recording |
**System Audio is optional** and only matters for meetings. macOS files
system-audio capture under the same permission as screen recording, which is
why that's the pane the app opens — for meetings OpenWhispr captures audio only
and never records your screen. It needs macOS 14.2 or later; below that the
option isn't available.
**Screen Recording is optional too**, and only used if you turn on **Share
screen context** for the voice agent. With it on, pressing the voice agent
hotkey captures a single screenshot of the display your cursor is on and sends
it with that one command — it is never saved, stored, or logged. Leave the
setting off and no screenshot is ever taken.
### When Accessibility looks granted but pasting fails
This is the common one, and it's macOS behaviour rather than a bug. Replacing
the app — an update, a reinstall, a rebuild — can leave a stale entry pointing
at the old copy while the new one has no access.
In **Settings** → **Privacy & Data** → **Permissions**, open **Troubleshooting**
and use **Reset accessibility permissions**. That removes OpenWhispr from the
list so you can add it back cleanly. [Updates and
reinstalling](/help/fix/updates-and-reinstalling) has the full sequence.
## The Globe key
On a Mac the default dictation hotkey is the **Globe** (fn) key —
one key, nothing to hold alongside it, and nothing else on the system wants it.
It asks for no permission beyond the three above.
That's macOS-only. The Globe key can't be used as a hotkey on Windows or Linux,
and neither can the mouse-button hotkeys OpenWhispr also accepts here. You can
change it, and there are four other slots — Voice Agent, Translation, Meeting
Mode and Chat Agent — under **Settings** → **Hotkeys** under **App**. [Your
hotkeys](/help/dictation/hotkeys) covers all five.
## The menu bar and the Dock
OpenWhispr lives in the menu bar. Click the icon to show the dictation panel or
open Settings.
The **Dock icon follows the control panel** — it appears when the control panel
is open and goes away when you close it. A tray-only launch shows no Dock icon
at all, which is intentional rather than a failed start.
## Updates
OpenWhispr checks for updates at launch and tells you when one is available. It
doesn't download anything until you say so. Apple Silicon and Intel builds are
tracked separately, so you always get an update for the Mac you're actually on.
Your version is under **Settings** → **System**, under **Updates**, next to
**Current version**.
## Uninstalling
From your Applications folder.
```bash theme={null}
rm -rf ~/.cache/openwhispr/
```
```bash theme={null}
rm -rf ~/Library/Application\ Support/OpenWhispr/
```
This deletes local settings, dictation history and any notes that were
never backed up to the cloud. Notes you did back up come back when you
sign in again.
## Related
* [System requirements](/platform/system-requirements)
* [Dictating into other apps](/platform/dictating-into-other-apps)
* [Where your files live](/platform/where-your-files-live)
* [The text doesn't paste](/help/fix/text-not-pasting)
# Mobile and tablets
Source: https://docs.openwhispr.com/platform/mobile
Whether there's an iPhone, iPad or Android app — the honest current answer, and how to get on the beta.
OpenWhispr is a desktop app today: **macOS, Windows and Linux**. There is no
app to download on the App Store or Google Play yet.
## iOS and iPadOS
An iOS app is built and not yet released. It isn't on the App Store, so there's
nothing to search for.
**There is a TestFlight beta**, and we're happy to add you. Email
[support@openwhispr.com](mailto:support@openwhispr.com) from the address on
your account and ask — you'll get the invite and, if you'd rather just be told
when it launches properly, we'll add you to the notification list instead.
It's a beta in the ordinary sense: rough edges, changes between builds, and
your feedback genuinely lands on the person building it.
## Android
There's no Android app, and no date we can honestly give you. If you want one,
say so to [support@openwhispr.com](mailto:support@openwhispr.com) — demand is
what moves it up the list, and we count it.
## If you saw "mobile app" on a plan
You read it correctly and we owe you the context: our pricing page lists a
mobile app under the paid plans, and it isn't downloadable yet. That's our copy
running ahead of the release, not something missing from your account, and
we're fixing the page.
Nothing about your plan changes when the app does ship — if mobile is listed on
your plan, it's included when it arrives.
## In the meantime
* **Cloud backup** keeps your notes available wherever you sign in — it's off
by default and needs a paid plan. [Sync across
devices](/help/notes/sync-across-devices) covers what syncs and what doesn't.
* **The API** works from anywhere, including a phone, if you want to build
something now. [API overview](/api/overview) is the starting point.
## Related
* [System requirements](/platform/system-requirements)
* [Sync across devices](/help/notes/sync-across-devices)
* [Plans and limits](/help/plans-and-limits)
# Running in the background
Source: https://docs.openwhispr.com/platform/running-in-the-background
The tray icon, the floating panel, starting with your computer, and the small settings that decide how much OpenWhispr is in the way.
OpenWhispr is meant to be forgotten about until you press the hotkey. It runs
from the system tray, shows a small floating panel while you dictate, and stays
out of the way otherwise.
Everything on this page lives under **Settings** → **Preferences** under
**App**.
## The tray icon
The tray icon — menu bar on macOS, system tray on Windows and Linux — is how
you reach the app when no window is open. Click it to show or hide the control
panel; right-click for the menu.
Closing the control panel window doesn't quit OpenWhispr. That's deliberate: it
has to keep running to hear your hotkey. Quit properly from the tray menu when
you actually want it gone.
The **Dock icon follows the control panel** — it appears when the panel is
open and disappears when you close it. Launching straight to the tray shows
no Dock icon at all.
Windows hides tray icons it doesn't recognise. If OpenWhispr seems to have
vanished, click the `^` caret at the right of the taskbar — it's usually
there. Drag it out to keep it visible.
The tray icon depends on your desktop supporting tray icons at all. Some
minimal Wayland setups don't; the app still runs and the hotkey still
works.
## The floating panel
The floating panel is the small window that shows you're recording.
| Setting | Default | What it does |
| ----------------------- | ------------ | ------------------------------------------------------------ |
| **Auto-hide when idle** | Off | Keeps the panel hidden until you start dictating |
| **Start position** | Bottom Right | Where it appears: Bottom Right, Bottom Center or Bottom Left |
You can drag the panel anywhere; the start position is where it comes back on
launch. If it's ever off-screen — usually after unplugging an external monitor
— restart the app and it returns to the start position.
## Starting with your computer
| Setting | Default | Notes |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Launch at login** | Off | Starts OpenWhispr when you log in, straight to the tray. **macOS and Windows only** — the setting isn't shown on Linux |
| **Start minimized** | Off | Launches without opening the control panel window |
On Linux, use your desktop environment's own autostart to achieve the same
thing.
## Sound and appearance
| Setting | Default | What it does |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| **Theme** | Auto | Light, Dark, or match your system |
| **Dictation sounds** | On | A tone when recording starts and stops |
| **Pause media** | Off | Pauses music automatically when dictation starts, and resumes after. Works on all three platforms |
Dictation sounds are worth keeping on to begin with — they're how you learn
whether the hotkey registered without watching the screen.
## Notifications
Four separate switches, all on by default:
* **Meeting detection** — tells you a meeting was detected so you can start
recording
* **Calendar reminders** — tells you a scheduled meeting is about to start
* **App updates** — tells you a new version is available
* **Disable all notifications** — silences everything except errors
## Related
* [Settings reference](/help/customise/settings-reference)
* [Your hotkeys](/help/dictation/hotkeys)
* [OpenWhispr won't open](/help/fix/app-wont-open)
# System requirements
Source: https://docs.openwhispr.com/platform/system-requirements
What OpenWhispr needs on macOS, Windows and Linux — and what the on-device models need on top of that.
OpenWhispr is a desktop app for macOS, Windows and Linux. There's no web version
and no browser extension: it runs on your machine so it can hear your
microphone and type into whatever app you're using.
## The short answer
| | Minimum |
| -------------- | ---------------------------------------------------------------- |
| **macOS** | macOS 12 (Monterey) or later, Apple Silicon or Intel |
| **Windows** | Windows 10 or later, 64-bit (x64) |
| **Linux** | 64-bit (x86-64), PulseAudio or PipeWire for audio |
| **Everywhere** | A microphone, and an internet connection for cloud transcription |
Dictating with **OpenWhispr Cloud** asks very little of your computer — the
transcription happens on our servers. Running models **on your own device** is
the demanding part, and it's covered below.
## Running models on your device
Local transcription and local AI models are downloaded on first use and run
entirely on your machine. Two things matter: disk space for the model, and
enough speed to keep up with you.
* **Disk** — a small Whisper model is a few hundred megabytes; the larger ones
run to several gigabytes. Local reasoning models are larger again. Everything
lives under a cache folder you can clear later — see [where your files
live](/platform/where-your-files-live).
* **Speed** — a recent Apple Silicon Mac or a machine with a discrete GPU runs
the bigger models comfortably. On older hardware, pick a smaller model or use
the cloud. [Local models](/guides/local-models) explains the trade-off and
which model to start with.
* **Graphics acceleration** — Metal on Apple Silicon works with no setup. On
Windows and Linux, NVIDIA cards use CUDA and AMD or Intel graphics use a
Vulkan runtime you can install from Settings in one click.
Some on-device components need a newer operating system than the app itself
does. If a local model downloads but won't start, tell us your exact OS
version when you write in — that's the first thing we check.
## What needs a newer macOS
Two capabilities are gated on the macOS version rather than on your hardware:
| Capability | Needs |
| ---------------------------------------------------------------- | --------------- |
| Dictation, cloud and local transcription, notes | macOS 12+ |
| **System audio capture** — recording the other side of a meeting | **macOS 14.2+** |
Below macOS 14.2 the app can still record a meeting through your microphone; it
just can't capture what the other participants are saying. [Capture both sides
of a meeting](/help/meetings/capture-both-sides) covers what that means in
practice.
## Architecture and downloads
Two separate downloads — one for **Apple Silicon**, one for **Intel**. Pick
the one that matches your Mac; if you install the Intel build on an Apple
Silicon machine by mistake, OpenWhispr notices and moves you onto the Apple
Silicon build at the next update.
64-bit **x64** only. There's no separate ARM build.
64-bit **x86-64** only, as `.AppImage`, `.deb`, `.rpm` or `.tar.gz`. There's
no ARM build, so Raspberry Pi and ARM laptops aren't supported today.
## Network
The app talks outbound over HTTPS on port 443, and everything else it runs
binds to your own machine by design. It honours system proxies on all three
platforms. If your network filters outbound traffic, [network
allowlist](/help/it/network-allowlist) is the page to hand your firewall
administrator.
Local transcription works with no internet connection at all, once the model is
downloaded.
## Related
* [macOS](/platform/macos) · [Windows](/platform/windows) · [Linux](/platform/linux)
* [Local models](/guides/local-models)
* [Cloud or local processing](/guides/cloud-vs-local)
# Where your files live
Source: https://docs.openwhispr.com/platform/where-your-files-live
Every folder OpenWhispr writes to on each platform — settings, history, logs, downloaded models and note files.
OpenWhispr keeps everything in two places: an application-data folder for your
settings and history, and a cache folder for downloaded models. Both are inside
your user account, so nothing needs administrator access to read or remove.
## Application data
Your settings, dictation history, debug logs and any saved audio:
| Platform | Folder |
| ----------- | ------------------------------------------ |
| **macOS** | `~/Library/Application Support/OpenWhispr` |
| **Windows** | `%APPDATA%\OpenWhispr` |
| **Linux** | `~/.config/OpenWhispr` |
Inside it:
| Item | What it is |
| ------------------- | ---------------------------------------------------------- |
| `transcriptions.db` | An ordinary SQLite database holding your history and notes |
| `logs/` | Debug logs, when debug logging is on |
| `audio/` | Recordings kept by your audio-retention setting |
Deleting this folder resets OpenWhispr completely: settings, history, and any
notes that were never backed up to the cloud. Notes you did back up return
when you sign in again.
## Downloaded models
Local speech and AI models are downloaded on first use and cached outside the
application-data folder, so you can reclaim the space without losing settings:
| Platform | Folder |
| ------------------- | ---------------------------------- |
| **macOS and Linux** | `~/.cache/openwhispr/` |
| **Windows** | `%USERPROFILE%\.cache\openwhispr\` |
Whisper models sit in `whisper-models/` inside it. Deleting anything here is
safe — the app re-downloads what it needs next time you select it.
You don't have to do it by hand: **Settings** → **System** → **Data
Management** → **Model cache** has **Open**, which shows you the folder, and
**Clear cache**, which empties it. **Reset app data** in the same section is the
bigger hammer — it deletes local settings, transcriptions, recordings and
models together.
On Windows the uninstaller clears this folder for you. On Linux, `.deb` and
`.rpm` packages do the same on removal; AppImage and tar.gz don't, because
there's no uninstaller to run.
## Note files, if you turned them on
**Save notes as files** (under **Settings** → **Preferences** under **App**)
mirrors your notes as Markdown into a folder you choose. It's off until you
turn it on, and the location is entirely yours — the app writes into it and
nothing else does.
That folder is also the Obsidian answer: point it at a vault and your notes
appear there as ordinary Markdown. [Export your
notes](/help/notes/export-your-notes) covers the detail.
## Credentials
API keys and enterprise credentials aren't in either folder. They go to the
operating system's own credential store — Keychain on macOS, DPAPI on Windows,
libsecret on Linux — and are never sent to us. [How OpenWhispr is
secured](/help/privacy/how-openwhispr-is-secured) explains the one Linux caveat
worth knowing on managed fleets.
## Backing up
If you want a copy of everything local, take the application-data folder while
OpenWhispr is closed. Copying `transcriptions.db` while the app is running can
catch it mid-write.
The models cache isn't worth backing up — it re-downloads.
## Related
* [What we store and for how long](/help/privacy/what-we-store-and-for-how-long)
* [Where your data goes](/help/privacy/where-your-data-goes)
* [Updates and reinstalling](/help/fix/updates-and-reinstalling)
# Windows
Source: https://docs.openwhispr.com/platform/windows
Installing on Windows, why no permission prompts appear, hold-to-talk, and how meeting audio is captured.
OpenWhispr on Windows sits in the system tray. Unlike macOS, it needs no
permission grants to type into other applications — everything works from the
moment you finish onboarding.
## What you need
* **Windows 10 or later**, 64-bit (x64)
* A microphone
## Installing
Download the `.exe` installer from the [releases
page](https://github.com/OpenWhispr/openwhispr/releases/latest) and run it. It
lets you choose the install location and creates a desktop and Start Menu
shortcut.
The app is code-signed as **Gizmo Labs Inc.** If Windows SmartScreen or your
antivirus flags it anyway — which happens to newly signed applications before
they build reputation — [antivirus blocks
OpenWhispr](/help/fix/antivirus-blocks-openwhispr) explains what to check and
what to send us.
A **portable** build is published alongside the installer. It runs without
installing anything, which helps on a machine where you can't run installers.
The installer is the supported path for everyone else.
During installation OpenWhispr adds a **Windows Firewall rule that blocks
inbound connections** to the bundled local-transcription server. That server
only ever serves this app over `127.0.0.1`; the rule exists so Windows doesn't
show you a firewall prompt for it, and it closes the port to the rest of the
network. If the installer can't elevate, it skips the rule silently and nothing
breaks.
## Permissions
There are none to grant. The app says so during onboarding: *"Windows does not
require special permissions for automatic pasting. You're all set!"*
Microphone access is governed by Windows' own privacy settings rather than by
OpenWhispr. If no audio is being captured, check **Settings → Privacy →
Microphone** in Windows, then [the microphone isn't
working](/help/fix/microphone-not-working).
## Hotkeys and hold-to-talk
The default dictation hotkey is Ctrl+Win.
Windows supports **hold-to-talk** — hold the key while you speak, release to
stop — through a native keyboard listener that ships with the app. The same
listener is what makes **modifier-only** hotkeys work, like Ctrl +
Win with no letter, and right-side-only modifiers.
Windows also reserves a long list of shortcuts for itself — anything starting
Win+E, Win+L, Alt+Tab
and friends. OpenWhispr refuses those with an explanation rather than binding
something that will never fire. [Choosing a shortcut that
works](/help/dictation/choosing-a-shortcut) has the rules.
## How text gets pasted
OpenWhispr copies the transcription to your clipboard and simulates the paste
keystroke into whatever window has focus, then puts your previous clipboard
contents back.
It sends Ctrl+V to ordinary applications and
Ctrl+Shift+V to terminals, which it identifies
by the foreground window — Windows Terminal, the classic console host (Command
Prompt and PowerShell), ConEmu, mintty (Git Bash), PuTTY, Alacritty, WezTerm,
kitty, Hyper and MobaXterm by window class, plus Termius, Tabby, Wave and Rio
by executable name.
[Editors, IDEs and terminals](/platform/editors-and-terminals) covers what to
do when your terminal isn't on that list.
## Meeting audio
Windows can capture the other side of a call with no permission prompt and no
screen-share picker. OpenWhispr records everything the computer is playing
*except itself*, so your own playback never loops back into the recording.
One known exception: the **new Microsoft Teams** client doesn't always expose
its call audio this way. [Meeting audio isn't
captured](/help/fix/meeting-audio-not-captured) covers the symptom and the
workaround.
## Updates
OpenWhispr checks for updates at launch and tells you when one is available; it
downloads only when you agree, then installs quietly on quit. Your version is
under **Settings** → **System**, under **Updates**, next to **Current
version**.
## Uninstalling
Uninstall from **Settings → Apps** as normal. The uninstaller removes
downloaded models from `%USERPROFILE%\.cache\openwhispr\` for you.
For a clean slate, also remove the app data:
```batch theme={null}
rd /s /q "%APPDATA%\OpenWhispr"
rd /s /q "%LOCALAPPDATA%\OpenWhispr"
```
That deletes local settings, dictation history and any notes never backed up
to the cloud.
## Related
* [System requirements](/platform/system-requirements)
* [Dictating into other apps](/platform/dictating-into-other-apps)
* [OpenWhispr won't open](/help/fix/app-wont-open)
* [The text pasted twice](/help/fix/text-pasted-twice)
# Work and managed computers
Source: https://docs.openwhispr.com/platform/work-computers
Installing where IT has locked things down, what to send your security team, and the settings that make OpenWhispr fit a restrictive policy.
Plenty of people install OpenWhispr on a work machine. This is what to do when
that machine has opinions.
## If your company manages OpenWhispr
Your normal setup should be short:
1. Install and open OpenWhispr.
2. Enter your work email and choose the company SSO option.
3. Finish sign-in in your browser.
If IT assigned you through SCIM, the app immediately receives your workspace,
teams, policies, and managed Amazon Bedrock or Azure OpenAI defaults. You do not
need an invitation, AWS CLI profile, cloud API key, role ARN, tenant ID, or model
name.
During a company pilot, email/password sign-in may still appear as a secondary
option. It lets existing employees test OpenWhispr before IT enforces SSO. Once
**Require SSO** is enabled for the verified company domain, that fallback is
blocked.
If sign-in says you are not assigned, contact your OpenWhispr workspace owner.
Your directory administrator needs to activate your SCIM assignment; there is
nothing to repair on the computer.
## If you can't run an installer
| Platform | Option |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Windows** | A **portable** build is published alongside the installer. It runs without installing anything |
| **Linux** | The **AppImage** runs from your home directory with no package manager involved — note that browser sign-in needs a `.deb` or `.rpm`, so use an email code instead. See [Linux](/platform/linux) |
| **macOS** | If you can't write to `/Applications`, drag OpenWhispr into `~/Applications` instead. It works the same |
Nothing OpenWhispr installs requires administrator rights to *run*, and
everything it writes stays in your user account — see [where your files
live](/platform/where-your-files-live).
## If the network is filtered
The app makes outbound HTTPS connections on port 443, and everything else it
runs binds to your own machine by design. It honours system proxies on all
three platforms.
[Network allowlist](/help/it/network-allowlist) is written to be forwarded to a
firewall administrator: the hostnames, split into what's required and what's
optional.
Local transcription needs the internet exactly once — to download the model.
After that it works offline entirely.
## If security software blocks it
New signed applications get flagged before they build reputation, and
OpenWhispr's Windows build has been caught by Norton in the past.
[Antivirus blocks OpenWhispr](/help/fix/antivirus-blocks-openwhispr) covers what
to check and what to send us.
## If your policy says nothing may leave the device
That's a supported configuration, not an argument. Choose **Local** for
transcription and a local model for AI, and no audio or text reaches our
servers — or anyone else's.
Two settings worth pairing with it:
* **Data Retention** off, if nothing should be written to disk either.
* **Cloud backup** stays off unless you turn it on. It already is by default.
[Where your data goes](/help/privacy/where-your-data-goes) has the full picture,
mode by mode.
## What to send your security team
One page: [answering a security
review](/help/privacy/for-your-it-team). It collects the DPA, privacy policy,
security overview, trust centre and compliance posture, plus what the product
does with data — the questions a vendor review asks, answered in the order they
usually arrive.
If your organisation is on an active Enterprise workspace, its owners can
configure SSO, SCIM lifecycle management, provider allowlists, retention,
sharing, and managed Bedrock or Azure OpenAI access in the admin portal.
Business workspaces keep the ordinary sign-in and provider setup flows.
## Related
* [Answering a security review](/help/privacy/for-your-it-team)
* [SCIM provisioning](/help/it/scim-provisioning)
* [Managed Amazon Bedrock and Azure OpenAI](/help/it/managed-enterprise-ai)
* [Network allowlist](/help/it/network-allowlist)
* [System requirements](/platform/system-requirements)
# Quickstart
Source: https://docs.openwhispr.com/quickstart
Get OpenWhispr running in under five minutes.
Grab the latest release for your platform from the [releases page](https://github.com/OpenWhispr/openwhispr/releases/latest).
| Platform | Format |
| -------- | -------------------------------------- |
| macOS | `.dmg` (Apple Silicon and Intel) |
| Windows | `.exe` installer |
| Linux | `.AppImage`, `.deb`, `.rpm`, `.tar.gz` |
Open the installer and follow the prompts. On first launch, OpenWhispr walks you through an onboarding wizard.
* **OpenWhispr Cloud** — sign in with Google, Apple (macOS), Microsoft, or email for instant transcription
* **Bring your own key** — enter your OpenAI, Groq, or other API key
* **Local** — download a Whisper or Parakeet model (no internet needed after download)
* **Microphone** — required for voice recording
* **Accessibility** (macOS) — required for automatic text pasting
* **Screen recording** (macOS) — needed for meeting audio capture
Press your hotkey (Globe/Fn on macOS, Ctrl+Win/Ctrl+Super on Windows and Linux), speak, press again. Your text appears at your cursor.
## Building from source
If you prefer to build from source:
```bash theme={null}
git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr
npm install
npm run dev
```
Requires Node.js 24+. See the [contributing guide](/contributing) for build details.
## Next steps
* [Set up your AI agent](/guides/agent-mode)
* [Configure meeting transcription](/guides/meeting-transcription)
* [Explore the API](/api/overview)
# Common problems
Source: https://docs.openwhispr.com/troubleshooting
Find the fix for what's actually happening — start from the symptom.
Pick the thing that's going wrong. Each page is a single problem with the
checks that resolve it, in the order worth trying.
If something is broken rather than confusing, skip ahead to
[sending us a debug log](#send-us-a-debug-log) — it's the single most useful
thing you can attach to an email.
## Dictation
You spoke, and you got "No Audio Detected" or an empty result.
No microphones listed, permission denied, or the wrong device is picked up.
Re-transcribe from history, and recover something you cancelled.
Transcription works, but nothing lands in the app you're typing into.
Duplicated text on Windows.
Nothing happens on the shortcut, or another app has taken it.
Wrong names, wrong language, or accuracy that dropped.
You dictated a question and got a reply rather than your words.
## Meetings
Only your voice is recorded, or nothing is.
## Installing, launching and updating
Installed, but no window appears — or the panel is off-screen.
Windows Defender, Norton, or a firewall prompt.
Failed updates, permissions that stopped working, and a clean reinstall.
## Network, models and cloud
Connection errors, corporate proxies and certificate warnings.
Downloads that fail, stall, or fail to install afterwards.
Whisper or Parakeet on your own machine.
Every host the app contacts, for firewalls, proxies and DNS filters.
## Account
Your subscription went through and the app hasn't caught up.
What the limit actually is, and when it frees up.
## Linux
Wayland clipboard behaviour and PipeWire capture.
## Getting help
Email **[support@openwhispr.com](mailto:support@openwhispr.com)** — a real
person reads every message, on every plan. Tell us your operating system, your
OpenWhispr version (**Settings → System**, under **Updates** — look for
**Current version**), and what you were doing when it went wrong.
### Send us a debug log
If something is failing rather than just confusing — dictation producing nothing,
a transcription erroring, audio not being picked up — a debug log usually turns a
few days of back-and-forth into a single reply. It's the most useful thing you
can attach. Debug mode records what OpenWhispr is actually doing — audio
processing, API requests and system operations — so a problem that's hard to
describe becomes something we can read.
Open **Settings**, choose **System** under **System**, and switch on
**Debug mode** under **Debug Logging**.
The log only captures what happens while debug mode is on, so reproduce the
issue after switching it on.
Click **Open Logs Folder** in the same **Debug Logging** section. The path to
the current log is shown there too, under **Current log file**.
Send us the newest file in that folder along with your email.
Prefer the command line, or need debug mode on before the app finishes
starting? Launch with `--log-level=debug`, or set `OPENWHISPR_LOG_LEVEL=debug`
in the `.env` file in your app data directory.
Debug logs are plain text files, so you can open one and read it before you send
it. They're a record of what the app was doing rather than a copy of your notes,
though some entries include short excerpts of what was said or generated —
commonly the first 100 characters of a transcript or AI response, and in a few
cases (like a raw transcription-service reply) up to around 1,000 characters —
logged as-is with no redaction. Skim the file before sending, and tell us if
you'd rather redact or trim a section — we can work with a partial log.
Switch debug mode off once you've sent the log — it writes to disk continuously.
* [Discord](https://discord.gg/yZWC9WTtX7) — ask other users
* [GitHub Issues](https://github.com/OpenWhispr/openwhispr/issues) — for
reproducible bugs and feature requests, if you'd rather file one
* [Getting help](/help/getting-help) — what to include, and where to go for what