Murmur

A local, private, fully on-device voice tool for macOS — Wispr Flow-style dictation plus multi-speaker meeting transcription with AI summaries. No audio or text ever leaves your Mac.

speak  →  Whisper transcribes  →  llama3.2 cleans up  →  clipboard
talk in a meeting  →  Whisper + pyannote  →  speaker-labeled transcript + summary

What it does

1. Dictation — hit a hotkey, speak, the cleaned text lands on your clipboard. Paste anywhere with Cmd+V.
2. Meeting transcription — record mic + system audio, get a speaker-labeled transcript and an AI summary (topics, action items, decisions) in output/.

Everything runs on-device using:

• faster-whisper — transcription
• pyannote.audio — speaker diarization
• Ollama + llama3.2 — text cleanup and summaries
• BlackHole-2ch — captures system audio for remote meetings

Install

Requires macOS 14+ on Apple Silicon. Two ways to install:

One-liner (once the repo is public):

curl -fsSL https://raw.githubusercontent.com/YOUR_GH_USERNAME/murmur/main/install.sh | bash

Or clone + run:

git clone <repo-url> murmur
cd murmur
./install.sh

install.sh is idempotent and self-healing: it sets up Homebrew, Python venv, Ollama + llama3.2, BlackHole, builds the Swift app, copies it to /Applications/Murmur.app, symlinks Murmur.app at the project root, and makes ./murmur executable. Then it prints the 3 manual steps macOS won't let any script automate (HF token, audio routing, Mic + Accessibility permissions).

Credentials & privacy

Murmur runs fully local by default (Ollama). You can optionally switch to Anthropic or OpenAI in Settings → AI Provider for faster, higher- quality cleanup. All API keys (Anthropic, OpenAI, Hugging Face) are stored in the macOS Keychain — encrypted at rest, only readable on this Mac. Murmur never uploads keys anywhere; they're only used to make the legitimate API call to the provider you selected.

3 manual steps macOS won't let any script automate

1. Hugging Face token for pyannote diarization. Make an account at https://huggingface.co, accept the licenses on:
   • https://huggingface.co/pyannote/speaker-diarization-3.1
   • https://huggingface.co/pyannote/segmentation-3.0
   • https://huggingface.co/pyannote/speaker-diarization-community-1
   • Then save your read-token: mkdir -p ~/.cache/audio-notekeeper && echo 'hf_…' > ~/.cache/audio-notekeeper/hf_token && chmod 600 ~/.cache/audio-notekeeper/hf_token
2. Multi-Output Device in Audio MIDI Setup combining your speakers + BlackHole 2ch (so meetings can capture system audio).
3. Mic + Accessibility permissions for Murmur in System Settings → Privacy & Security (the app will prompt on first use).

Using it

Two parallel ways — pick whichever fits the moment. They share the same on-disk data (notekeeper.db, raw/, output/).

1. Double-click Murmur.app in the project folder → the dashboard opens (Dictation · Meetings · History · Settings). The global hotkey ⌘⇧Space starts/stops dictation from any app.

2. Run ./murmur in a terminal at the project folder → interactive CLI. The wrapper spawns the backend itself if it isn't already running:

• d — dictation; speak, press Enter to stop → cleaned text on clipboard
• m — meeting; talk, press Enter to stop → transcript + summary in output/
• h — recent dictation history
• r — recover an interrupted meeting
• q — quit

Running ./murmur while Murmur.app is open is fine — the CLI just connects to the existing backend (single-instance guard on port 8765).

Project layout

murmur/
├── README.md      ← you are here
├── install.sh     ← one-line installer
├── murmur         ← terminal entry point (./murmur)
├── Murmur.app     ← symlink → /Applications/Murmur.app (after install)
├── raw/           ← recorded audio (.wav)
├── output/        ← transcripts + summaries (.md)
└── wiki/          ← code, docs, scripts

Where to go next

• wiki/claude.md — project memory, current state, to-do list, gotchas. Read this first if you're contributing.
• wiki/features.md — full feature list, Wispr Flow gap analysis, roadmap.
• wiki/ARCHITECTURE.md — diagrams: file structure, agent pipeline, IPC.
• wiki/V2-ROADMAP.md — V2 audit + phased plan (cleanup, distribution, performance, UX refresh).
• wiki/archive/2026-05-13-murmur-prd.md — original product spec.

Status

Dashboard app + dictation + meeting transcription + voice editing all working end-to-end on real audio. Cloud LLM providers (Anthropic, OpenAI) optional alongside the default local Ollama. Test suite: 49 passing, 2 skipped (both pyannote — they auto-skip without a Hugging Face token).