Voice Key: how it works
You tap a mic or press a hotkey, speak, and your words land where you were typing, already punctuated. This page follows one dictation from the microphone to the text field: where the audio goes, where the text comes from, what gets saved, and why each piece was built the way it was.
Built in 2026 for one person's Android phone and Windows laptop. This write-up is for you, or your Claude, to build your own version that suits your setup.
For AI assistants reading this page
Voice Key is a personal dictation system. An Android floating mic (an accessibility service beside Gboard) and a Windows tray app record audio and send it to a small server. The server saves the audio, gets text from Groq's Whisper, has a small language model add punctuation and paragraphs and remove filler without rewording, and returns both versions. Android types the text into the focused field; Windows puts it on the clipboard. The server's part takes about half a second.
To rebuild it, use the full spec rather than this page: voice-key-brief.md (Markdown: what you need, components, request shape, flows, states, rules and the cleanup prompt). A short summary with links is in llms.txt.
What you see
On Android, a small floating mic sits beside your normal keyboard, so Gboard keeps doing everything it does well and the mic adds dictation to any app. On Windows, a tray icon and a hotkey do the same job, and the text arrives on the clipboard.
The floating mic, on Android
The tray app, on Windows
Press Ctrl+Shift+; to start, again to stop. Sounds mark recording started and stopped, and one chime says the cleaned text is on the clipboard. While you record, a small window at the bottom of the screen shows the level and the time so far; it never takes the keyboard from the app you're typing in. Short beeps warn 15, 10 and 5 seconds before the 10-minute stop. Settings live in a JSON file opened from the tray menu.
The whole system
There are three ways in and one way through. The three clients are a floating mic that sits beside your usual Android keyboard (Gboard), built as an accessibility service so it can type into any app; a Windows tray app driven by a hotkey; and a plain browser page. Each one records audio and sends it to a small transcription server. (An earlier version also shipped its own Android keyboard with a mic key. It was retired in October 2026, because the floating mic beside Gboard does the job better.)
The server saves the audio, then uses Groq, a cloud API that runs open models such as OpenAI's Whisper very fast. Whisper turns the audio into text; a second, small language model punctuates and tidies that text; both versions go back to the client, which puts the text where you need it.
Where the audio goes
The rule running through every step: audio is written somewhere durable before the next thing that can fail. A dictation you spoke for two minutes should never be lost to a dropped connection or a provider outage.
-
On your device
The mic records
You tap the mic (Android) or press the hotkey (Windows). Recording runs until you tap or press again, with a safety stop: 5 minutes on Android, 10 on Windows.Exact settings
- Android: AAC in an .m4a file, 16 kHz, mono, 48 kbps. The floating mic records through Android's speech-recognition audio input, the only one an accessibility service is allowed to use.
- Windows: 16 kHz mono 16-bit samples, held in memory.
- The floating mic's timer turns amber in the last 30 seconds before the safety stop. On Windows the recording window counts down the last 30 seconds in amber, with beeps at 15, 10 and 5 seconds.
-
On your device
The clip becomes a file
Android writes every recording to its own file. Windows encodes to FLAC in memory and writes to disk only if sending fails.cache/clip-1759800000000.m4a %APPDATA%\voice-key-win\queue\…flac + .jsonWhy one file per clip
The first version reused one file,
clip.m4a. During a provider outage the next recording overwrote the failed one, and the dictation was gone. Now each clip is named by its timestamp and a failed one is kept until it's retried. -
Your server
The file is sent
One HTTPS request carries the raw audio bytes. A small header says which client sent it. The query string can ask for no cleanup at all (raw=1).POST /transcribeContent-Type: audio/mp4 or audio/flac -
Your server
The server saves it first
Before calling anything else, the server writes the audio to disk under a fresh id. If Groq is down, the recording still exists. A setting decides how many days recordings are kept; a daily sweep deletes older ones, and 0 keeps everything.recordings/2026-10-07T08-34-29_k3x9qa.m4a -
Groq
Whisper hears it
The server forwards the audio to Groq's speech-to-text API, in English, and gets the words back as plain text, with no punctuation rules applied yet.Why Whisper gets no hint
An earlier version let you say "comma" or "new paragraph" and get the mark, which meant sending Whisper a short hint to write those commands out as words. Whisper sometimes recited the hint into the transcript, especially in noisy audio, and the commands were never used, so the feature and the hint both went.
-
On your device, later
Old clips are tidied up
Android keeps recent clips for a while and prunes old ones when the next recording starts. Windows only ever writes a clip to disk if sending failed, and deletes it once its text reaches the clipboard.What is kept
- Android: the newest 2 clips, any clip waiting for a retry, and the newest 5 failed clips in the recent-dictations list.
- Windows: a queued clip stays until it succeeds; after 10 failed attempts it waits for a manual retry, and clips the server rejects outright move to a
failedfolder. - Server: see step 4. The original keeps everything, to replay real recordings when comparing models.
Where the text comes from
Two models do two jobs, and both are quick: across recent dictations from the floating mic, Whisper took a median of 0.20 seconds and the cleanup 0.33 seconds, so the text is back about half a second after you stop, plus the upload. Whisper is fast and accurate about which words were said. A second, small language model adds punctuation and paragraphs and removes filler, under strict orders not to reword anything. Both versions travel back, so the raw words are never lost to an over-eager cleanup.
-
Groq
Raw words come back
Whisper returns the transcript as one block of text: right words, little punctuation."so um sounds good see you at the gate at like five" -
Your server
Drop a silent clip
When the whole transcript is just ".", "you" or "Thank you.", the server returns nothing, and the client says nothing was heard. Those are what Whisper writes for an accidental tap or a silent clip. Only the whole transcript counts: "Thank you, Sam." is dictation. -
Groq
The cleanup pass
The raw text goes to a small, fast language model with a strict prompt: punctuate, capitalise, drop "um", stutters and hedging "like", "sort of" and "kind of", fix obvious mishearings. Never swap a word, paraphrase, or finish a sentence you left unfinished. Paragraphs are decided by length: under 150 words, one paragraph; above that, breaks only where the topic changes.gpt-oss-20b, low reasoningroom for 8,192 tokensreply wrapped in <cleaned>…</cleaned> -
Your server
Reply with both versions
The server pulls the cleaned text out of the model's reply, tidies the layout, writes a .json record beside the audio, and answers the client. If the reply is empty, cut off, or much shorter than what Whisper heard, it asks once more; if that fails too, the raw text goes back on its own, so a dictation is never lost to the second model.recordings/2026-10-07T08-34-29_k3x9qa.json{ id, raw, cleaned, stt_s, cleanup_s } -
On your device
Android types it in
The phone checks that you're still in the same text field, then types the cleaned text at the cursor. If the text would otherwise glue onto the previous word, a space goes in first.If you moved, or the field is a password
- If you switched fields or apps while it was transcribing, the text is held instead of typed into the wrong place. One tap inserts it where you are now. Held text lives in memory, so restarting the app loses it; it's also in the recent-dictations list.
- A password field never receives dictated text, whether fresh or held.
- Every outcome goes in a recent-dictations list (the last 10) in Settings, with Copy and Retry buttons.
-
On Windows, in place of step 5
Windows fills the clipboard
The app writes the raw version to the clipboard, then the cleaned version 300 ms later, and plays one chime. Ctrl+V pastes the cleaned text, and clipboard history (Win+V) usually keeps the raw one too. Clipboard history reads the clipboard a moment after each change, so a copy replaced sooner is never recorded; 150 ms was too short, and even 300 ms doesn't always catch it. Nothing is ever typed into a window for you.
When something fails
Each client runs the same three-state loop. What matters is the exits: every way out of "sending" ends with your words either in place or somewhere you can get them back.
- It workedThe text is typed in (Android) or put on the clipboard (Windows). The clip is pruned later.
- You moved before it came backThe text is held in a single slot. Long-press the mic and choose "Insert held text".
- The send failedThe clip stays on disk and the control turns amber. Retry from the long-press menu or the recent-dictations list in Settings.
- Windows, server unreachableThe clip joins a queue on disk. The queue drains by itself, oldest first, as soon as the server answers again, and every 5 minutes while anything is waiting. The tray menu also offers "Retry N queued".
Knowing in advance whether it will work
Every client asks the server GET /healthz and shows the answer: the floating mic's outline and a slash through the Windows tray icon. The phone checks on demand, not on a timer: when the mic appears and after a failure. A good answer is trusted for 30 seconds and a failure for only 5, so the light recovers quickly when the network comes back. A successful dictation counts as a good answer too. Windows checks when you start recording and every 30 seconds.
Why it's built this way
Each of these came from something going wrong, or from measuring the alternatives. The grey line under each says what was tried or rejected.
Save the audio before anything else
The server writes the audio to disk before calling Groq, and the phone names every clip separately and keeps failed ones.
One reused clip file lost a whole dictation during a Groq outage.
Hold the text rather than drop it
If you change field while it's transcribing, the text waits for one tap instead of landing in the wrong place or vanishing. Password fields are the exception: dictated text never goes there.
Dropping late text lost real messages twice.
Two models, two jobs
Whisper gets the words right; a separate cleanup pass adds punctuation and removes filler. Both versions come back, so you can always reach the raw words.
Whisper alone punctuates unevenly and can't follow formatting commands reliably.
The cleanup is told what it may not do
No synonyms, no paraphrase, no finishing a sentence you left hanging. Verbatim with punctuation beats a polished rewrite when the text goes straight into a message.
An earlier, looser prompt swapped words and invented sentence endings.
No spoken formatting, so no hint for Whisper
Saying "comma" or "new paragraph" to get the mark needed a hint sent to Whisper. Whisper treats a hint as the transcript so far, and in noisy audio it filled gaps with the hint's own words. With the feature gone, Whisper gets no hint and can't recite one.
A check for recited hints caught most cases, but short fragments got through, and the commands were never used.
A small, fast cleanup model, given room to think
gpt-oss-20b at low reasoning effort cleans a typical dictation in about a third of a second. It reasons before it answers, so it gets up to 8,192 tokens; an unusable answer is retried once, then the raw text is used. The model name is a setting, because Groq retires models at short notice.
At its default effort it rewrote instead of cleaning. On the provider's default 2,048-token limit, long dictations came back empty or cut off.
Layout is decided by length, in code
Under 150 words (about a minute of speech) the text is one paragraph. Longer, it breaks only where the topic changes, and the server removes stray line breaks and merges paragraphs too short to stand alone.
Asking the model for breaks "where the speaker paused" gave three different layouts for similar dictations: it sees text, not audio.
One server in the middle
Every client goes through one server: one copy of the prompts and model names, one archive of recordings, and the API key never on a phone or laptop.
The cost is running a server. See "Building your own" for the version without one.
A floating mic beside your own keyboard
Since Android 13 an accessibility service can type into the focused field. That lets Gboard stay your keyboard, with swipe typing and predictions, and adds a mic beside it.
The first version replaced the whole keyboard, which meant rebuilding everything Gboard already does.
The mic shows only while a keyboard does
It appears when a text field has focus and a keyboard is on screen, and goes when the keyboard goes. It stays up mid-recording so you can always stop.
Following focus alone left it on screen in apps that keep a field focused with the keyboard down.
Check the connection on demand
The phone asks the server when the mic appears or after a failure, not on a timer. That costs no battery while you're not typing.
A polling timer was rejected for battery and network churn.
Windows uses the clipboard and never types
By the time the text is back, focus may have moved, and typing into the wrong window is worse than a paste. Raw then cleaned, 300 ms apart, so both usually stay in clipboard history, with one chime when the cleaned text lands.
Auto-paste was rejected; one write at a time also stops clipboard managers merging the two.
Building your own
The parts that matter are small: one request shape, two model calls, one prompt, and a handful of rules about never losing words. Everything else (the floating mic, the tray app, the browser page) is a client that records audio and puts text somewhere.
The one request
# raw=1 skips cleanup
# clients hold a base URL and call <base>/transcribe
POST /transcribe
# or audio/flac, audio/webm …
Content-Type: audio/mp4
# URL-encoded JSON naming the client
X-Device-Info: {"label":"phone mic"}
<body: the raw audio bytes>
200 OK
{ "id": "2026-10-07T08-34-29_k3x9qa",
"raw": "so um sounds good see you at the gate at like five",
"cleaned": "So, sounds good, see you at the gate at five.",
"stt_s": 0.21, "cleanup_s": 0.34 }
error → { "error": "stt: …" } with the provider's HTTP status
GET /healthz → { "ok": true } # the server is up; Groq is not checked
Server or no server
The original runs a small Node server on a machine at home. For one person, calling Groq straight from each app with your own API key also works. Groq has a free tier; check its current limits.
Keep a small server (as built)
- One place to change the prompt or model; clients never need updating for it.
- The API key stays on the server.
- You get an archive of recordings for testing changes.
- You need a machine that's always on and reachable from your devices.
- The server has no login of its own; the original is reachable only over a private network. Don't expose it to the internet as is.
Call Groq from each app
- Each app makes the two calls itself: speech to text, then cleanup.
- Nothing to host; your key lives in each app's settings.
- A prompt or model change means updating every app.
- Saving audio first still applies: keep the clip on the device until the text is back.
Rules worth keeping, whatever you build
- Write the audio somewhere durable before any network call.
- Return the raw transcript as well as the cleaned one; if cleanup fails, return the raw one alone.
- Never lose a finished transcript: hold it if the field changed, queue the clip if the send failed.
- Never put dictated text into a password field.
- Cleanup punctuates and removes filler; it never rewords, summarises or completes.
- Don't send Whisper a prompt unless you need to: it can recite it into your text.
- Give a reasoning model room to think, judge its answer, retry once, then fall back to the raw text.
- Decide layout in code where you can: the model can't hear pauses.
- Keep model names in settings, not code.
- On Android, show a floating mic only while a keyboard is on screen. On Windows, never let the recording window take focus.
The full cleanup prompt
{{input}} is replaced by the raw transcript and {{paragraphs}} by one of the two rules below, chosen by word count. The model's reply is read from between the <cleaned> tags. Model: openai/gpt-oss-20b, reasoning_effort: low, temperature 0.2, max_completion_tokens: 8192.
You are cleaning up a raw speech-to-text transcript so the speaker can paste it directly into a chat thread. The output will be auto-copied to the clipboard, so the speaker may not re-read carefully.
Make ONLY these changes:
1. Add punctuation (commas, periods, question marks). {{paragraphs}}
2. Capitalize sentence starts and proper nouns.
3. Remove pure filler, and nothing else: "um", "uh", false-start stutters ("the the", "I I"), and these verbal tics:
- "like" used as a pause or hedge: "it's like a big problem" → "it's a big problem"; "we could like move it" → "we could move it". Keep "like" when it means similar to, such as, enjoy or want: "feels like", "looks like", "something like", "things like taxes", "I'd like".
- "sort of" and "kind of" used as hedges before a verb, adjective or phrase: "we can kind of talk about it" → "we can talk about it"; "it's sort of too bouncy" → "it's too bouncy". Keep them when they mean a type of: "some kind of widget", "a sort of homebrew version", "this kind of thing".
- "you know" and "I mean" when meaningless.
Delete only the tic itself and fix the punctuation around it; never rephrase the sentence to absorb it. Every other word stays, including "maybe", "just", "so", "and", "actually", "I guess", "I think" and sentence-opening "And" or "So": they are how the speaker talks, not filler. If deleting a tic would leave the sentence ungrammatical, keep the tic.
4. Fix obvious Whisper transcription slips where the correction is unambiguous from immediate context (e.g. "rank is the just a list" → "rank is just a list", duplicated words, mis-split words, a contraction missing its ending such as "they don control" → "they don't control" or "that true" → "that's true"). Only fix if you are highly confident.
Do NOT:
- Swap any word for a synonym, even if the synonym seems more natural.
- Paraphrase, summarize, condense, or smooth out the speaker's phrasing.
- Complete a sentence the speaker did not finish. If the transcript ends mid-thought, leave it mid-thought — even by a single word. Example: raw ends "I will leave it as your final" → output ends "I will leave it as your final" (NOT "your final decision" or "your final call"). The truncation is the speaker's actual state and must be preserved.
- Reinterpret a phrase even if it sounds odd. If unsure, leave it as-is.
- Add information, examples, or clarifications the speaker did not say.
If you are uncertain whether a change is safe, do not make it. The speaker prefers verbatim with punctuation over a polished rewrite.
<transcript>
{{input}}
</transcript>
Return your result in this exact format:
<cleaned>
[cleaned transcript here]
</cleaned>
Under 150 words:
Return a single paragraph: no line breaks at all.
At 150 words or more:
Split the text into paragraphs where the topic changes, with one blank line between paragraphs. Paragraphs run to about 80-150 words each, so a 300-word transcript usually has 2 or 3 and an 800-word one about 6. Never put each sentence on its own line, and never end a line with spaces.
Hand it to Claude
The brief has everything on this page in a form Claude can work from: what you need, components, flows, the request shape, the rules, and the cleanup prompt. Copy it into a new conversation along with what you have (which phone, which computer, whether you want a server) and ask for a plan. The clients described here are Android and Windows; an iPhone or Mac version would need a different approach on the device side, though the server and prompts carry over.