Voicely

# Voicely **Free, open-source, offline dictation and transcription for macOS — with a local MCP server that gives Claude Code, Codex and Cursor ears.** <p align="center"> <a href="https://github.com/StulkovLD/Voicely/actions/workflows/ci.yml"><img src="https://github.com/StulkovLD/Voicely/actions/workflows/ci.yml/badge.svg" /></a> <img src="https://img.shields.io/badge/platform-macOS%2014%2B%20%C2%B7%20Apple%20Silicon-lightgrey" /> <img src="https://img.shields.io/badge/swift-6.0-orange" /> <img src="https://img.shields.io/badge/license-MIT-green" /> <img src="https://img.shields.io/badge/engine-Parakeet%20V3%20%2B%20FluidAudio-blue" /> </p> <p align="center"><img src=".github/assets/voicely-card.png" alt="Voicely — Speak. It types. Open source, offline, free." width="600" /></p> - **Dictate anywhere.** Press `Option+Space`, speak, press it again — the text lands wherever your cursor is, terminals and VS Code included. - **Calls and files.** Record a call (system audio + mic, no virtual audio device) and get a speaker-separated transcript; turn any audio or video file into text. - **Agent-native.** `voicely connect` registers a local MCP server, so your agent can transcribe files and read your calls and dictations. - **On-device only.** NVIDIA Parakeet V3 through CoreML, 25 languages. No account, no cloud, no subscription. MIT. ```bash curl -fsSL https://voicely.art/install.sh | sh # or brew install --cask stulkovld/voicely/voicely ``` macOS 14+ on Apple Silicon. Like Superwhisper, MacWhisper or Wispr Flow — but free and MIT-licensed, 100% on-device, and built to hand text to your AI agent. ## Free, forever Tools that do this usually ask for a monthly subscription or a one-time payment. Voicely is free, forever: MIT-licensed, and every line of it is in this repository. It is made by one person, in one room, who uses it every day. If it saves you time, a ⭐ helps others find it. ## Install One command. There is no DMG to download and nothing to drag into Applications: ```bash curl -fsSL https://voicely.art/install.sh | sh ``` Or through the Homebrew tap: `brew install --cask stulkovld/voicely/voicely`. The script downloads the current build, verifies its SHA-256 and its signing certificate in a private staging directory, installs it transactionally — the previous version stays as a backup until the new one passes every gate, and any failure rolls back cleanly — then launches the app. Re-running it updates in place and keeps your transcripts, model and settings. The public build is signed with Voicely's own certificate rather than an Apple Developer ID, and it is not notarized by Apple. The certificate is the same for every release, so macOS keeps your Microphone and Accessibility permissions when you update. If an older copy left permission entries behind, the installer clears them and Voicely asks again by itself. **First launch** 1. Find the Voicely icon in the menu bar. 2. Allow **Microphone**, then switch Voicely on in the **Accessibility** list that opens. Voicely waits for both and continues by itself. 3. Confirm the speech model download (Parakeet V3, about 470 MB). The first prepare step takes about a minute; later launches are fast. 4. **Screen Recording** is requested only when you first use **Record Call**. Requirements: macOS 14 or newer on Apple Silicon. ## Transport, not translation Voicely moves what you said to where you work. It never rewrites, summarizes or "improves" what you meant — word-level truth is kept next to every transcript. ### Direct transport — dictation, `Option+Space` Press the hotkey, speak, press it again. A floating glass pill shows the live waveform while you talk. The text lands wherever your caret is: native Mac fields through Accessibility, checked by reading the caret back; Chrome, VS Code, Claude and every other Chromium or Electron app through the clipboard and `⌘V` — your clipboard is put back right after the app has read the text, and the transcript is marked so clipboard managers don't keep it; terminals through typed text. If no app takes the text, it waits on the clipboard and the pill says "Press ⌘V". The **Output** menu can pin dictation to the clipboard permanently; secure fields are save-only, always. Dictations are saved to `~/Documents/Voicely/dictations/`; where each one went, and how, is logged without the words in `~/Library/Logs/Voicely/insertion.jsonl`. ### Careful packaging — calls and files **Calls** (menu bar → Record Call). Voicely records system audio (through ScreenCaptureKit — no virtual audio device needed) and your microphone, mixes them into one track, transcribes the mix and diarizes it globally. An echo can't duplicate a sentence, and several people on one mic separate into distinct voices. "You" is identified by matching diarized voices against your microphone's own activity. The transcript reads as speaker turns and is saved to `~/Documents/Voicely/calls/<id>/` as markdown, word-level JSONL and WAV. **Files.** Any audio or video file becomes a transcript, with optional speaker diarization: `voicely transcribe <file>` from the terminal, or the `transcribe_file` tool from an agent. Results land in `~/Documents/Voicely/files/`. Either way the result is text in one tap. Hand it to your agent yourself — paste it into Claude Code, save it as a note — or let the agent read it through MCP, below. ## Your AI knows what you know The `voicely` CLI and a local MCP server make every capability agent-native. After installing the app, expose the CLI on your PATH and register the server with the agents you use: ```bash /Applications/Voicely.app/Contents/Helpers/voicely setup # symlinks `voicely` into /usr/local/bin or ~/.local/bin, no sudo voicely connect # registers the MCP server with every installed harness voicely connect claude # or one by name: claude, codex, cursor, hermes, openclaw ``` Claude Desktop and other MCPB-aware clients can install the server in one click from `voicely-<version>.mcpb` on the [latest release](https://github.com/StulkovLD/Voicely/releases/latest). Voicely is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=voicely) as `io.github.StulkovLD/voicely`. Teach the agent the whole playbook with the skill: ```bash mkdir -p ~/.claude/skills/voicely && \ curl -fsSL https://voicely.art/skill/SKILL.md -o ~/.claude/skills/voicely/SKILL.md ``` `voicely mcp` speaks standard stdio MCP (JSON-RPC 2.0, fully offline) and exposes four tools: | Tool | What it does | |------|--------------| | `transcribe_file` | Transcribe an audio/video file (optional speaker diarization) | | `list_transcripts` | List saved transcripts (dictations / calls / files), newest first | | `get_transcript` | Read a transcript by id or alias (`last`, `last-call`, …) | | `get_last_call` | Read the most recent call transcript | `voicely connect` uses each harness's own `mcp add` command and never hand-edits a config file it doesn't own. Restart the agent afterward and ask it: *"transcribe ~/Downloads/interview.m4a and pull the action items"*, *"look at my last call and draft a project plan"*, *"what did I dictate earlier?"*. The skill covers bootstrap from zero, online video via yt-dlp (YouTube / TikTok / Instagram) and "watching" a video by pairing word-level timestamps with extracted frames. Everything stays on the machine. **Manual config** — register `voicely mcp` as a stdio server. The exact file differs per harness; the shape is always `command: voicely`, `args: ["mcp"]`: | Harness | Where | How | |---|---|---| | Claude Code | plugin or `claude mcp add` | `claude mcp add voicely -- voicely mcp` (or the [bundled plugin](integrations/claude-code/voicely/)) | | Codex | `~/.codex/config.toml` | `[mcp_servers.voicely]`<br>`command = "voicely"`<br>`args = ["mcp"]` | | Cursor | user settings | `cursor --add-mcp '{"name":"voicely","command":"voicely","args":["mcp"]}'` | | Hermes | `~/.hermes/config.yaml` | `hermes mcp add voicely --command voicely --args mcp` | | OpenClaw | `openclaw.json` | `openclaw mcp set voicely --command voicely --args mcp` | | Anything else | its MCP config | `{"mcpServers":{"voicely":{"command":"voicely","args":["mcp"]}}}` | There is no daemon: the server loads the speech model itself on the first `transcribe_file` call. ## Build from source macOS 14+ on Apple Silicon and the Xcode Command Line Tools (`xcode-select --install`): ```bash git clone https://github.com/StulkovLD/Voicely.git cd Voicely swift build -c release --product Voicely swift build -c release --product VoicelyCLI .build/release/Voicely # the menu-bar app .build/release/VoicelyCLI setup # exposes the `voicely` command ``` > In SPM the CLI product is **VoicelyCLI**, not `voicely`: on case-insensitive APFS a `voicely` product would collide with the app binary `Voicely`. The `voicely` command is created by `setup`, in a directory with no such collision. ## Speech model **Parakeet TDT 0.6B v3** (NVIDIA, CC-BY-4.0), running on-device through FluidAudio's CoreML port: about 470 MB on disk, 25 European languages including English and Russian — switching languages mid-sentence works — natively punctuated, roughly 30× realtime on Apple Silicon. Speaker diarization uses FluidAudio's pyannote community-1 segmentation and WeSpeaker embeddings, also on-device. Models download on first use; no Hugging Face account or token is required. ## Transcripts Everything is plain files under `~/Documents/Voicely/` — readable by you, your agent and any other tool. **Dictation** (`dictations/`): ```markdown --- type: dictation date: 2026-03-19T22:30:00+00:00 source_app: Telegram --- Your transcribed text here. ``` **Call** (`calls/<id>/transcript.md`): one block per speaker turn; your own microphone is always `You`. Word-level timing lives in `transcript.jsonl` next to it; the audio is kept as `mix.wav` (what was transcribed) plus the raw `mic.wav` and `system.wav`. ```markdown --- type: call date: 2026-08-19T18:02:11+03:00 source_app: zoom.us duration: 12:40 speakers: You + 2 --- [00:08] You Hey, how's the project going? [00:11] Speaker 1 Almost done, pushing to prod tonight. [00:17] Speaker 2 I'll review the PR after lunch. ``` ## Architecture ``` Option+Space ──> MicRecorder ──> Parakeet V3 (CoreML, on-device) ──> CursorInjector │ AX insert (native) → ⌘V, clipboard restored → typed text v │ AudioOverlay v (liquid glass pill) TranscriptStore (~/Documents/Voicely/…) ``` ``` Record Call ──> mic + ScreenCaptureKit ──> mixdown ──> Parakeet V3 ──> FluidAudio diarization ──> speaker-turn markdown (one track) ("You" by mic activity) + word-level JSONL + WAV ``` **Stack:** Swift 6 + AppKit + FluidAudio (Parakeet TDT v3 CoreML + diarization) + ScreenCaptureKit (system audio). All processing happens locally. No data leaves your machine. ## Autostart on login System Settings → General → **Login Items** → **+** → add **Voicely.app**. ## Acknowledgements - **Parakeet TDT 0.6B v3** by NVIDIA (CC-BY-4.0) — the speech model. - **FluidAudio** (Apache-2.0) — CoreML ports of Parakeet and the on-device diarization pipeline. - **Diarization models** — pyannote segmentation and WeSpeaker embeddings (CC-BY-4.0). - **WhisperKit** (MIT) — the on-device inference library this project grew up on. ## License MIT