🎙️ SuperWhisper Trainer

Teach SuperWhisper your vocabulary — function names, product names, acronyms, and jargon — so it stops mishearing the words you use every day.

What it does

SuperWhisper transcribes your speech well — until you say useState, wp_remote_post, or your company's product name, and it writes "use state", "WP remote post", or something worse. SuperWhisper Trainer builds the replacement rules and vocabulary list that fix those mistakes, then writes them straight into your SuperWhisper settings.

You can build that config three ways:

1. From a preset — start with the bundled developer or slack rules.
2. From practice — read a script aloud and let the trainer suggest fixes from what it mishears.
3. From your own history  ✨ NEW — mine the dictations you've already done to find the terms you actually use (the learn command). See Train from your history.

flowchart LR
    A[Preset] --> C
    B[Practice session] --> C
    D[Your recording history] --> C
    C[Config: replacements + vocabulary] --> E[trainer.py train]
    E --> F[(SuperWhisper settings.json)]

Loading

Note

This is a macOS tool. SuperWhisper stores its settings and recordings under ~/Documents/superwhisper/, and the trainer reads and writes there locally — nothing is ever uploaded.

How it works

A replacement rewrites what you said into what you meant:

You say:        "the use state hook and console log"
SuperWhisper:   "the use state hook and console log"
After training: "the useState hook and console.log"

Both rules above ship in the developer preset. A vocabulary entry doesn't rewrite anything — it tells SuperWhisper a term exists (e.g. PostgreSQL, ActiveCampaign) so it's more likely to transcribe it correctly in the first place.

trainer.py loads rules from a preset or a YAML/JSON config, backs up your current SuperWhisper settings, and merges the new rules in. Restart SuperWhisper and they take effect.

Installation

Important

Requires Python 3.8+, macOS, and SuperWhisper installed. The only dependency is PyYAML.

# Clone
git clone https://github.com/verygoodplugins/superwhisper-trainer.git
cd superwhisper-trainer

# Virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Dependencies
pip install -r requirements.txt

# Copy the config template
cp config.example.json config.json

Having trouble installing PyYAML? See README_SETUP.md for Homebrew and pipx alternatives.

Quick start

# 1. Preview what a preset would change — no files touched
python trainer.py test --preset developer --text "use state hook"
#    → "useState hook"

# 2. Apply a preset to SuperWhisper (backs up your settings first)
python trainer.py train --preset developer

# 3. Restart SuperWhisper to load the new rules

Prefer a guided experience? python interactive_setup.py walks you through checking your SuperWhisper install and picking a model, and python interactive_trainer.py runs a read-aloud practice loop with live accuracy feedback.

Commands

python trainer.py <command> [options]

Command	What it does
train	Load a preset/config and apply it to SuperWhisper (with backup)
apply	Alias for train — load a preset/config and write it to SuperWhisper
test	Show what replacements would do to a phrase, without saving
benchmark	Score before/after accuracy on test phrases
analyze	Scan a text file for technical terms worth adding as rules
learn  🆕	Build a config from your own SuperWhisper recording history
practice	Launch the interactive read-aloud training loop (same as python interactive_trainer.py)
progress	Show stats from your past practice sessions

Common options

Option	Applies to	Default	Purpose
--preset NAME	train, apply, test, benchmark	—	Use a bundled preset (developer, slack)
--config PATH	train, apply, test, benchmark	—	Use a custom YAML/JSON config
--text VALUE	test (phrase), analyze/benchmark (file)	—	Inline text to test, or a file to analyze/benchmark
--mode NAME	train, apply	default	Apply only rules tagged with this mode (e.g. slack)
--no-backup	train, apply	off	Skip backing up settings before writing
--source PATH	learn	~/Documents/superwhisper/recordings	Recordings folder to learn from
--output PATH	learn	user_configs/from_history.yaml	Where to write the suggested config
--hints PATH	learn	—	Steer the run (systems/misspellings/suppress) — see Steer it with hints
--dry-run	learn	off	Print suggestions without writing a file

Examples

# Test a custom config against a phrase
python trainer.py test --config my_terms.yaml --text "deploy to kubernetes"

# Apply only Slack-mode rules (backticks, emoji, markdown)
python trainer.py train --preset slack --mode slack

# Find candidate rules hiding in a document
python trainer.py analyze --text meeting_notes.txt

# Benchmark a config against your own phrase list
python trainer.py benchmark --config my_terms.yaml --text test_phrases.txt

Configuration

A config is YAML (or JSON) with two sections — both optional:

# my_terms.yaml
replacements:
  - from: "wp fusion"
    to: "WP Fusion"

  - from: "use state"
    to: "useState"

  # `mode` tags a rule so it only applies under `train --mode slack`
  - from: "user id"
    to: "`user_id`"
    mode: "slack"

vocabulary:
  - PostgreSQL
  - GraphQL
  - ActiveCampaign

Apply it the same way as a preset:

python trainer.py train --config my_terms.yaml

See example_config.yaml for an annotated starting point.

Note

These rule files (passed via --config) are separate from config.json — the small file you copy from config.example.json during setup, which only records where SuperWhisper is installed. You don't edit config.json to add replacements.

Bundled presets

Preset	For	Example rules
developer	Programming terms	use state → useState, console log → console.log
slack	Chat formatting	backtick-wrapped code, emoji shortcuts, bold headers

Have a good domain preset (medical, legal, scientific, another language)? Those are exactly what the project is looking for — see CONTRIBUTING.md.

🧠 Train from your history  ✨ NEW

Tip

New in this release. learn batch-processes your whole SuperWhisper history at once, and it's model-agnostic — it reads saved transcripts, not audio, so it works no matter which model (Turbo, Parakeet, a cloud model, …) produced each recording.

Instead of guessing which terms you need, mine the dictations you've already done. The learn command reads your SuperWhisper recording history, finds the vocabulary and code-style tokens you actually say, and writes a reviewable config:

# Mine the recordings on this Mac
python trainer.py learn

# Preview without writing anything
python trainer.py learn --dry-run

🧠 LEARNED FROM YOUR SUPERWHISPER HISTORY
  • Recordings scanned: 128 (119 with text)
  • Words analyzed:     8400
  Found 64 vocabulary candidates and 7 replacement candidates.
💾 Saved suggested config to: user_configs/from_history.yaml

It mines three things: vocabulary you say often, replacement candidates for spoken code tokens, and known-term fixes — fuzzy matches against a curated list of commonly mis-transcribed names in data/known_terms.yaml. Speech models write "Claude Code" a dozen ways; learn maps cloud code, clawed code, and Claude code all back to Claude Code. It also skips anything already in your settings. (That list is meant to grow — add your stack's terms and open a PR.)

Review the file, delete anything wrong, then apply it like any other config:

python trainer.py train --config user_configs/from_history.yaml

Steer it with hints

The miner only knows your transcripts. You know your stack, the words your voice model always botches, and the look-alikes it should leave alone. Feed that in with a hints file:

python trainer.py learn --hints user_configs/learn_hints.yaml

# full schema: data/learn_hints.example.yaml
systems: [Cube, dbt, WP Fusion]   # extra known terms to fuzzy-match
misspellings:                      # forced — always included, exactly as written
  - from: "active campaign"
    to: "ActiveCampaign"
suppress: [cloud code]             # NEVER "fix" these (you really mean cloud infra)

suppress is the cure for predictable false positives: if you say cloud code to mean cloud infrastructure (not the Claude Code product), list it and learn won't rewrite it.

Tip

Using this repo inside Claude Code? The learn-coach skill (.claude/skills/learn-coach/) runs the whole flow as a short interview — asks about your stack and mis-hears, writes the hints, flags risky suggestions, and brainstorms improvements. Optional; the --hints flag works on its own.

Caution

The suggested config is derived from your personal dictation, so it's written to a git-ignored path by default. The learn command is a local read — it never uploads anything. To train across multiple Macs or from iOS, see docs/IMPORTING_HISTORY.md.

Supported models

SuperWhisper offers several Whisper models. Faster models give the snappiest feedback while you train; larger models transcribe tricky terminology more accurately.

Model	Size	Speed	Best for
Turbo	39 MB	~10× realtime	Daily use, quick notes, interactive training
Base	74 MB	~5× realtime	Technical discussion, moderate accuracy
Small	244 MB	~3× realtime	Documentation, technical writing
Medium	769 MB	~1.5× realtime	Critical transcription, complex terminology

Note

Model choice affects live transcription, not learn — that command reads the saved transcripts, so it works the same across every model above.

Contributing

Contributions are welcome — especially domain-specific presets (medical, legal, scientific, non-English) and documentation fixes. Run the tests before submitting:

python -m unittest discover tests

See CONTRIBUTING.md for the preset format and PR process, and add yourself to CONTRIBUTORS.md.

Known limitations

• SuperWhisper must be restarted after applying changes.
• Replacements can conflict; there's no conflict detection yet.
• SuperWhisper caps the number of replacements (currently ~1000).
• learn heuristics suggest candidates from your speech — always review before applying.

Roadmap

• Conflict detection between replacement rules
• Automatic cross-device history import (iCloud / SSH) — see docs/IMPORTING_HISTORY.md
• More bundled domain presets
• GUI for configuration management

License

MIT

Acknowledgments

• SuperWhisper for the transcription app
• OpenAI Whisper for the underlying models

---

Made with 🧡 by Very Good Plugins