Build Superwhisper

YESreplaces $8.49/mosaves $101.88/yrback to the verdict

0%0 of 20 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

Hold a hotkey, speak, release, and the text appears in whatever field had focus, transcribed by a Whisper model running on your own machine, shaped by a mode that knows whether you are writing an email or a commit message, with a custom vocabulary so names and jargon come out right.

estimated effort weekendthe files for this build are in the project pack

LanguageSwift 6 and SwiftUI in XcodeTranscriptionwhisper.cpp with a locally downloaded modelAudioAVAudioEngine capturing to 16 kHz mono 16 bitRewritingAn optional model call, local or hosted, per modeInsertionPasteboard plus a synthetic Cmd-V, with the previous contents restored

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installfree if you already own one
Why Audio capture, hotkeys and text insertion are all platform APIs.
Get it Apple menu, then About This Mac.
Verify About This Mac reports macOS 14 or higher
installfree
Why Builds and signs the application and links whisper.cpp.
Get it Mac App Store or developer.apple.com/xcode. open ↗
Verify xcodebuild -version prints 16 or higher
installfree; models range from tens of megabytes to several gigabytes of disk
Why It is the transcription engine. Without a model there is nothing to transcribe with.
Get it Build whisper.cpp from its repository, then download a model. Start with a small English model to keep the ratio measurement quick, and try a larger one once the pipeline works. open ↗
Verify whisper-cli transcribes a 16 kHz mono WAV correctly
decidefree
Why Push-to-talk limits recording to when you hold the key, but the microphone still captures whatever is audible in that window.
Get it System Settings, then Privacy and Security, then Microphone. The usage description string must be in Info.plist or the prompt never appears.
Verify Recording produces audio with a level above silence
account99 USD per year
Why Product phase only. Without it there is no notarization and a Gatekeeper warning everywhere else.
Get it Enrol at developer.apple.com/programs. open ↗
Verify A Developer ID Application certificate appears in Xcode settings

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- modes(id, name, hotkey, model_size, rewrite_enabled, rewrite_prompt, target_apps_json)
- transcripts(id, mode_id, at, audio_ms, raw_text, final_text, model, transcribe_ms, rewrite_ms)
- vocabulary(id, term, sounds_like, mode_id) · names and jargon that Whisper gets wrong, with corrections applied after transcription
- settings(key, value) · audio device, whether to keep recordings, retention period
- Recordings are deleted after transcription by default. Keeping them is a setting the user turns on, not a default they discover.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`WHISPER_MODEL_PATH`	required	`~/Library/Application Support/Dictate/models/ggml-base.en.bin`	Where the downloaded model lives. Modes may point at different sizes.
`AUDIO_SAMPLE_RATE`	required	`16000`	Fixed by whisper.cpp. Capture at this rate directly rather than resampling.
`KEEP_AUDIO`	required	`false`	Whether recordings are retained after transcription. False by default and deliberately so.
`AUDIO_RETENTION_DAYS`	optional	`7`	Only used when retention is enabled. Older recordings are deleted.
`REWRITE_ENDPOINT`	optional	`http://localhost:11434/v1/chat/completions`	Optional rewrite model. A local endpoint keeps everything on the machine; a hosted one does not, and the README must say which you chose.
`PASTE_RESTORE_DELAY_MS`	required	`250`	How long to wait before restoring the pasteboard. Too short races the paste.

The build, in order

1
Hotkey, capture and one transcription
Hold a key, speak, release, and see the text in a window.
1. RegisterEventHotKey for the press, and track the release. Push-to-talk avoids the whole problem of deciding when speech has ended.
  Files Hotkey.swift
2. AVAudioEngine with an output format of 16 kHz mono 16 bit. Microphone access is its own permission with its own usage string in Info.plist.
  Files Audio.swiftInfo.plist
3. Link the library or invoke the binary. Record transcription milliseconds against audio milliseconds for several utterances.
  Files Transcribe.swift
done when · tick each as it passes
watch out
- whisper.cpp expects 16 kHz mono 16 bit PCM and behaves badly with anything else. Configure the audio engine to deliver that format directly rather than capturing at the device's native rate and resampling afterwards, which is an extra step that introduces its own artefacts.
next phase
2
Getting text into the field you were in
The transcription lands in whatever had focus, without losing your clipboard.
1. Capture the existing pasteboard items first. Restore after a delay, and only if your value is still there.
  Files Insert.swift
2. Secure text fields refuse synthetic input by design. Detect and show a brief message.
  Files Insert.swift
3. A native editor, a browser field and a terminal. They behave differently and one of them will surprise you.
done when · tick each as it passes
watch out
- Do not type the text with one event per character. It drops characters under load, mangles anything outside ASCII, and behaves differently in every text engine.
- Restoring the pasteboard too quickly races the paste and restores before the target application has read it. Restore after a delay, and only if the pasteboard still holds what you wrote.
next phase
3
Modes
Dictating a commit message and dictating an email produce appropriately different text.
1. Hotkey, model, rewrite settings and application bindings per mode. Not a global setting with overrides.
  Files Modes.swift
2. Match the frontmost bundle identifier when recording starts, not when the hotkey is registered.
  Files Modes.swift
3. A small indicator naming the mode. Discovering the wrong mode after speaking for a minute is the failure this prevents.
  Files Indicator.swift
done when · tick each as it passes
watch out
- A larger model gives better transcription and a longer wait, and past a couple of seconds the pause breaks the flow that makes dictation worth using. Let each mode choose its own model size, so quick notes use a fast one and long-form uses a better one.
next phase
4
Vocabulary and rewriting
Names and jargon come out right, and the text reads like writing rather than speech.
1. Record what the model produced, then map it. Guessing at misrecognitions is far less effective than reading your own transcripts.
  Files Vocabulary.swift
2. Filler removal and punctuation. A prompt that invites improvement will rewrite your meaning.
  Files Rewrite.swift
3. A timeout or an error inserts the transcription. Losing dictated text because a rewrite failed is the worst outcome here.
  Files Rewrite.swift
done when · tick each as it passes
watch out
- A rewrite step can quietly change meaning as well as style, and once it has replaced the raw text you cannot tell. Store both, show the raw text when the user asks, and keep rewrite prompts narrow: remove filler and fix punctuation, not improve the message.
next phase
5
History, retention and privacy
You can find what you dictated last week, and nothing is kept that you did not choose to keep.
1. Immediately after transcription. Retention is opt-in and says where files are kept.
  Files Retention.swift
2. Full text search over transcripts. This is the feature that turns dictation into a record you can use.
  Files History.swift
3. One function covering transcript, audio and index. Test by searching for the deleted text.
  Files Delete.swift
done when · tick each as it passes
watch out
- Dictation captures whatever was said near the microphone, including things the user did not intend to record. Default to deleting audio at once, make retention a deliberate choice, and never make the history the only place a transcription exists without saying so.
6
Signing, notarization and updatesproduct builder
Others can install it, and the permission story is stated plainly.
1. Hardened runtime, Developer ID, notarytool, stapler. Confirm the microphone usage string is present.
  terminal
  xcrun notarytool submit Dictate.zip --keychain-profile AC --wait
2. Progress, checksum and resume. Record each model's licence.
  Files ModelDownload.swiftdocs/models.md
3. What is recorded, what is deleted, and whether anything leaves the machine, which depends on whether rewriting uses a hosted model.
  Files README.md
done when · tick each as it passes
watch out
- Whisper models are hundreds of megabytes to several gigabytes. Bundling one makes the download enormous and may not be permitted by its licence; downloading on first run needs a progress indicator, a checksum and a resumable transfer, because a failed model download leaves the application useless with no explanation.

what this build does not replace

The native interface polish of the commercial application.
A curated library of context presets.
Per-speaker voice adaptation.
Mobile dictation.
beautiful native UX
presets
vocabulary/profile tuning
app-wide polish
support

after v1, if you want it

Streaming transcription so text appears while you are still speaking
A mode that dictates directly into a terminal with shell-aware punctuation
Automatic vocabulary suggestions from corrections you make by hand

Need the files? The project pack on the verdict page hands your agent the whole brief · more dictation.