🖥️ Desktop app — macOS

Everything in this part is the Mac menu-bar app: it uses whisper.cpp and a local LLM server you run yourself.

🚀 Install

One line. The script installs the build dependencies with Homebrew, builds the app from source, and drops it in /Applications.

Terminal

curl -fsSL https://raw.githubusercontent.com/xajik/voice-to-md/main/install.sh | bash

Installs xcodegen, whisper-cpp and ffmpeg via Homebrew, then builds the app.
On first launch, grant Microphone and Accessibility access when macOS asks.
Re-running the installer keeps those grants — builds are signed with your Apple Development identity when one exists.
Download a Whisper model from Settings… in the menu bar — Base (~150 MB) is a great start.
Prefer to do it by hand? Follow the Quick Start on GitHub.

✨ Two modes

One hotkey for everywhere, one window for deep work.

⌨️ Global Dictation

Press ⌘⌥] in any app, speak, and the transcript is typed straight at your cursor. Terminal, browser, Slack — anything. A Spotlight-style pill shows what's happening.

📄 Untitled-1

📝 Agent Mode

Speak freely; a local LLM streams your words into a clean, structured document in real time — Markdown, plain text, or HTML. The raw transcript stays one click away. Start it from the menu bar.

🎛️ Agent Mode control panel

One floating, draggable capsule drives the whole session — and decides how your voice lands in the document.

Recording MD

Send · mic · status · Format / Edit / Append · output format · preview · read aloud · clear.

✈️ Send · ⌘↩

Flush immediately: transcribe what you just said and send it to the LLM now, instead of waiting for the word threshold or a pause. Enabled while recording and no call is in flight.

🎙️ Mic & status

Start, pause, resume. The label tells you what's happening — Recording, Processing, Paused — with errors surfaced inline.

📄 Format · default

Whole document + new words go to the LLM; it returns the complete restructured document. Best for free-form dictation — the model keeps improving the structure as you talk.

✏️ Edit

Your voice becomes an instruction: “change the subtitle to Weekly Notes”, “turn that list into a table”. Select text in the editor first and the edit focuses on it.

➕ Append

Speed mode for long documents: only the last 3 sentences + your new words are sent; the model returns just the new content, appended. Latency stays flat as the file grows.

🗂 Output format · MD / TXT / HTML

A dropdown picks what comes out: Markdown (default), plain text, or HTML. Each format ships its own rules + example to the LLM, works in every mode, and the file on disk gets the matching extension. Remembered across launches.

👁️ Preview

Opens the session document in the default app for its type — the browser for HTML, your editor for markdown or plain text.

🔊 Read aloud

Sends your current selection — or the whole document if nothing's selected — to macOS's built-in text-to-speech. Tap again to stop mid-sentence.

🗑️ Clear session

Wipes the recorded audio, transcript, and markdown for the current session after a confirmation prompt, leaving you with a blank document.

You speak. Audio is transcribed on-device by whisper.cpp in ~4-second chunks.
Words buffer up. At ~30 words, after a 5-second pause, or the moment you hit Send, the buffer flushes.
The mode and output format pick the prompt. Format rewrites the whole document, Edit applies your instruction (to the selection, if any), Append formats only what's new — in Markdown, plain text, or HTML.
Tokens stream straight into the editor — and the document on disk (.md / .txt / .html) is updated after every flush.

🪟 Window toolbar

Two buttons live in the Agent Mode window's own title bar, separate from the floating capsule — for starting fresh and getting back to where you left off.

Speech to Markdown

📝 New Session

Starts a brand-new session without closing the window. Whatever you were working on is already saved to disk — this just clears the editor for a fresh document.

🕘 Session History

Lists recent sessions by date with a short preview and their output format. Click one to restore it and keep recording straight into the same files.

🧠 Desktop dependencies & local LLM (macOS only)

Mac app only — the iOS app needs none of this. Global Dictation only needs whisper.cpp — installed for you. Agent Mode talks to a local LLM server running on your Mac (default http://127.0.0.1:8000/v1) that speaks the OpenAI request format — that's an API shape many local-LLM tools share, not a connection to OpenAI the company; nothing is sent to OpenAI. Pick one:

brew install xcodegen whisper-cpp ffmpeg   # build dependencies (install.sh does this)

omlx · Apple Silicon, fastest

http://127.0.0.1:8000/v1

brew install omlx then omlx serve <model> — Speech-to-Markdown's default port, zero config.

Ollama

http://127.0.0.1:11434/v1

ollama pull qwen3.5 (or gemma3), then ollama serve.

LM Studio

http://127.0.0.1:1234/v1

Grab a model in the app, start the local server.

llama.cpp

http://127.0.0.1:8080/v1

llama-server -m model.gguf --port 8080.

Recommended model	Why
Qwen3.5 27B (4-bit)	Best formatting quality; the default pick
Gemma 26B (8-bit)	Fast, great instruction following

Settings

Local LLM

Speaks the OpenAI API format (omlx, llama.cpp, LM Studio…) — not OpenAI itself

http://127.0.0.1:8000/v1 Refresh

3 models

Whisper Model

Speech-to-text (whisper.cpp, runs on-device)

using Base

📱 Mobile app — iOS

A separate app for iPhone & iPad — fully offline, none of the desktop dependencies.

📱 Now on iPhone & iPad

iOS 26+ · iPhone 15 Pro or newer (Apple Intelligence required) · 100% offline. The same Agent Mode with zero dependencies: SpeechAnalyzer transcribes on-device, Apple Intelligence (Foundation Models) formats the document. No third-party AI service is used — no LLM server, no whisper install, no settings, no network request of any kind. Works in airplane mode.

Speech to MD

Recent Sessions

14 Jul at 11:30 AM

Product Sync — July 10

13 Jul at 8:05 PM

Weekend Groceries

11 Jul at 1:20 PM

Book Ideas — Voice Notes

＋ New Session

14 Jul at 11:30 AM

# Product Sync — July 10 ## Decisions - Ship the iOS beta to TestFlight - Keep transcription fully on-device - Markdown stays the default format ## Action Items 1. **Igor** — App Store screenshots 2. **Design** — history layout on iPad 3. **QA** — edit and append modes ## Notes The dictation flow feels fast. Silence triggers the formatting pass about five seconds after you stop speaking, and the document updates live as the model streams.

Raw input 71 words

Recording MD

Session history with restore · live editor · Format / Edit / Append · MD / TXT / HTML · preview · Files-app access.