# System-Level Voice Dictation — talk instead of type (Kit 2)

A push-to-talk setup so you can press one key in ANY app — your terminal, your browser,
your notes, a text box on some random website — talk, and watch your words land at the
cursor. It runs on Deepgram's Nova-3 model, so it's fast, accurate, and you can teach it
the names and tools you say all day. Works on macOS, Windows, and Linux.

This is the one I'd set up first. When you work with AI all day, the bottleneck stops
being thinking and starts being typing. This removes it.

## Prerequisite
A Deepgram API key. Sign up at deepgram.com and create a key in the dashboard — search
for their free credit when you sign up; it lasts a long while at this kind of use. Keep
the key in an environment variable or your OS secret store, never hardcoded in a script.

## How to use it (any OS)
Two ways — both end with Claude building it for you:

- **Quick:** hit Copy, open Claude Code, paste this in, and say the line below.
- **Most reliable** (this one's a build, not a one-line paste, so let Claude read the
  whole thing): hit Download, then tell Claude: *"read ~/Downloads/voice-dictation-setup.md
  and build it for my OS."*

Either way, say:

> "I'm on [Mac / Windows / Linux]. Build this for me — the audio capture, the Deepgram
> streaming, a hotkey to start/stop, the step that types into whatever app I'm focused on,
> and a silence cutoff. Ask me for my Deepgram key and store it safely, and seed the
> vocabulary file with a couple of placeholders for me to fill in."

Claude detects your OS and builds the matching version — the mic capture, the streaming
connection, the hotkey, and the trick to type into whatever window has your cursor.

## What it builds
- **Audio capture** — streams your microphone to Deepgram in real time.
- **Deepgram Nova-3 streaming** — accurate transcription with punctuation and smart formatting.
- **A vocabulary list** — a plain text file where you list the proper nouns you say
  constantly: your company, your tools, the people you work with. Deepgram boosts them so
  it stops inventing words for names it doesn't know. This single thing is what takes it
  from "mostly right" to "I don't re-read it." Proper nouns only — don't pad it with common words.
- **Type-into-any-app** — each finished phrase pastes at your cursor, and your existing
  clipboard is restored right after. (Linux uses xclip + xdotool; Mac uses pbcopy + an
  AppleScript keystroke; Windows sends Ctrl+V.)
- **A hotkey toggle** — press to start, press again to stop. (Linux: a key listener or your
  window-manager binding. Mac: Hammerspoon, Karabiner, or a Shortcut. Windows: AutoHotkey.)
- **A silence cutoff** — if you go quiet for about 30 seconds it stops itself, so a session
  you forgot about doesn't keep streaming and burning credits. (Deepgram bills per minute of audio.)
- **A status dot** (optional but worth it) — green when it's listening, red when it's not,
  so you always know if the mic is hot.

## The two things that bite people
- **Mic clipping.** If your mic gain is boosted too hot, the audio clips and the transcripts
  turn to word-salad. It looks like the model got dumber — it didn't, the audio did. Have
  Claude set a sane capture level, and re-check it first if quality ever drops.
- **Key safety.** Keep the Deepgram key in an env var or secret store. Never write it into a script.

## If Claude needs the exact specs
Deepgram's streaming (websocket) API, model `nova-3`, 16 kHz mono audio, interim results on,
punctuation and smart formatting on, and pass your vocabulary file in as `keyterms` — that's
the part that fixes the spelling of your names and tools. Type from the final transcripts, and
set the silence cutoff around 30 seconds.

## Make it stick
Have Claude set it to start on login, so the hotkey and the indicator are always ready.

You're done when you can press your key in any app, talk, and accurate text appears at your
cursor — including your own product and people names — stopping on a second press or after
a short silence.

That's Kit 2. I'd set this up before anything else — it pays for itself in the first hour.

-- Cliff (connectwithcliff.com)