open-dictate Hold a key, speak, let go. The words land at your cursor.

1. 01 Record

   while you hold the key

   Hold fn or right Option. The app records 16 kHz mono audio. Presses under half a second are dropped, and a speech-shape gate catches accidental recordings of room noise.

   rec = 3.4 svalues from the demo above

2. 02 Transcribe

   what was said

   MLX Whisper runs on Apple Silicon inside a daemon that stays loaded. Guards drop known subtitle-credit hallucinations and cut runaway repetition before anything goes further.

   model = large-v3-turbovalues from the demo above

3. 03 Correct

   what you meant

   Your glossary is a table of wrong → right pairs. Only pairs that match are applied; the sentence is never rewritten. A missed correction is better than a wrong one.

   changes = 2values from the demo above

4. 04 Punctuate

   how it reads

   The default smart_zh rules make marks full-width in Chinese context and leave English, numbers and URLs alone. An optional local LLM pass adds fuller punctuation and is thrown away if it changes anything else.

   punct = "smart_zh"values from the demo above

5. 05 Insert

   where it lands

   The text goes in through the Accessibility API, with paste as the fallback. The app never takes focus from the field you were typing in.

   insert → AX · pastevalues from the demo above

Words used on this page

Push-to-talk

Hold a key while you speak, release to finish. Open Dictate uses fn or right Option.

Daemon

dictated.py, the background process that keeps the model loaded so a short sentence needs no cold start. The app talks to it over a Unix socket.

MLX Whisper

The Whisper speech model running on Apple’s MLX framework. Default: whisper-large-v3-turbo.

Glossary pair

One wrong → right entry, such as git hub → GitHub. Applied exactly as written wherever the wrong side appears.

Contextual pair

A pair that is only safe in some sentences. It is never applied blindly; it waits for context or for you.

Review queue

Candidate pairs waiting for accept, edit or reject. Decisions are kept in a history and can be undone.

smart_zh

The default, rule-based punctuation: half-width marks after Chinese become full-width. Deterministic and idempotent.

No-rewrite gate

The check an optional LLM output must pass: with punctuation removed, it must match the input except for authorised glossary pairs.

SPEAKER_00

An anonymous speaker label in a meeting transcript. When the system is unsure who spoke, it says unknown rather than guess a name.

On the way to an ordinary Mac app

1. Phase 0Release architecture. One product config, data in Application Support, nothing at runtime that needs the clone.
2. Phase 1Self-contained beta. Python inside the app, a welcome flow for permissions and the model, a test DMG. Goal: first dictation in ten minutes on a clean Mac, Finder only.
3. Phase 2Signed and notarized. Developer ID, Apple notarization, a DMG that opens without Gatekeeper warnings, with checksums.
4. Phase 3Updates and rollback. Signed in-app updates, Stable and Beta channels, automatic rollback that never touches your data.
5. Phase 4More channels. Homebrew Cask; the Mac App Store only after the sandbox questions are answered.

The distribution roadmap →

The full privacy model →

git clone https://github.com/frank890417/open-dictate.git
cd open-dictate
./install.sh        # venv, app, LaunchAgents, model warm-up

./scripts/doctor.sh            # read-only checks, then a real ping
./uninstall.sh                 # removes the app and LaunchAgents, keeps ~/.open-dictate
./uninstall.sh --purge-data    # shows where your data is; never deletes it

# Meeting Mode: a local recording in, a reviewable package out
python3 daemon/meeting_cli.py transcribe ~/Desktop/meeting.m4a --out /tmp/od-meeting --language zh

# the review queue: look, then decide
python3 daemon/glossary/cli.py candidates
python3 daemon/glossary/cli.py accept cand_xxxxx

Full setup guide →

hold fn
  |
OpenDictate.app (Swift)       records 16 kHz mono PCM16 WAV
  |  {"cmd": "transcribe", "wav": "/tmp/...wav", "punct": "smart_zh"}
  v
/tmp/open-dictate.sock        newline-delimited JSON
  |
dictated.py (Python, warm)
  |-- MLX Whisper             audio -> raw text
  |-- glossary pairs          raw -> corrected   (muse_lexicon)
  |-- punctuation             smart_zh | llm_zh (gated) | raw
  |-- log                     ~/.open-dictate/dictation-log/
  v
{"ok": true, "text": "...", "raw": "...", "changes": [...]}
  |
OpenDictate.app  ->  Accessibility insert (paste fallback)  ->  cursor

meeting.m4a   or   segments.json / .jsonl
  |
meeting_cli.py transcribe
  |-- MLX Whisper             audio files only
  |-- glossary pairs          the same deterministic table
  |-- speaker labels          SPEAKER_00, SPEAKER_01 (anonymous)
  |-- QA flags                possible mishearings, numbers
  v
transcript.md  .jsonl  .srt  .vtt  meeting-result.json

# requests: one JSON object per line on /tmp/open-dictate.sock
{"cmd": "transcribe", "wav": "/tmp/open-dictate-rec-....wav", "punct": "smart_zh"}
{"cmd": "ping"}
{"cmd": "reload_lexicon"}
{"cmd": "add_pair", "wrong": "誤聽", "right": "正確", "source": "dictate-ui"}
{"cmd": "stats"}

# responses
{"ok": true, "text": "校正後文字", "raw": "whisper 原始輸出", "changes": [["誤聽", "正確"]], "punct": "smart_zh"}
{"ok": false, "error": "no_speech"}

./build.sh
python3 -m unittest discover tests
python3 scripts/golden-bench.py --skip-daemon
python3 scripts/public-safety-scan.py
./scripts/smoke-test.sh        # builds, tests, exports a meeting demo, checks the signed app

Docs

Documents mix English and Traditional Chinese; a few are in one language only.

• IO-CONTRACT.mdPaths, the socket protocol, glossary schema, correction rules, quality gates
• SetupRequirements, permissions, hotkey conflicts, doctor, uninstall
• Privacy modelData classes, where they live, what may never be committed
• Meeting ModeInputs, the pipeline, the segment schema, the safety rule
• Self-evolving glossaryThe review loop, its commands and its four buckets
• Speaker identityAnonymous labels now, optional local profiles later
• macOS distributionFrom install script to a signed, notarized, updatable app
• MCP roadmapA local, consent-gated MCP server, phase by phase
• ContributingGround rules and the commands to run

Next, from the roadmap

1. Local speaker profiles, enrolled with consent, stored only on your Mac
2. A menu-bar view for reviewing glossary candidates
3. Import and export for glossary packages you own
4. An app that runs without the clone, developer Python or Xcode tools
5. A Developer ID signed, notarized DMG tested on clean Macs
6. Signed in-app updates, rollback, Stable and Beta channels

Roadmap in the README →