transcribe-audio

name	transcribe-audio
description	Transcribe audio or video to text with a locally-run speech-to-text model. Use when the user wants a transcript or captions from a recording, wants to run speech-to-text locally instead of a cloud service, or wants to set up or switch their local transcription model.
compatibility	Needs a shell, Python 3, and ffmpeg. Default models target Apple Silicon (MLX via uvx); other platforms work but supply their own model command in the config.
metadata	{"author":"nweii","version":"1.0.0"}

Transcribe audio

Produce a transcript from an audio or video file using the model configured on this machine.

Check for a config first

Settings live in ~/.config/transcribe-audio/config.json.

• Missing — the machine isn't set up. Read references/setup.md and run setup (staging area, then model choice) before transcribing. Don't pick a model unprompted: the right one depends on the user's hardware, languages, and whether they want speed or accuracy, and a wrong guess wastes a large download.
• Present — go straight to transcribing.

When the user asks to change or upgrade their model, route to references/setup.md as well.

Transcribe

Run the bundled script on the file:

python3 <skill-dir>/scripts/transcribe.py /path/to/recording.mp4

The script extracts a 16kHz mono WAV (so audio and video files are handled the same way), runs the configured model, and writes the transcript to the staging area.

• --outdir DIR — write the WAV and transcript somewhere other than the staging area.
• --format srt — timestamped captions instead of prose; txt (default), vtt, and json also work.

Run it in the foreground and let its output stream. Throughput is high, but a multi-hour file still takes real time, and a silent run reads as stalled.

Offer to fix errors when accuracy matters

Auto-transcripts fail in predictable spots: proper nouns — names, products, jargon — get misheard, and audio over music or crosstalk garbles. Whether to fix this depends on use. A transcript the user skims once needs nothing; one they'll quote, publish, or keep as a record is worth a pass.

Flag, don't silently correct: you're inferring what was said, and a confident wrong fix buries the error where the user won't catch it. Read the whole transcript first, and ground proper nouns in whatever context exists — project notes, a glossary, the surrounding conversation — rather than substituting a similar-sounding name from your own knowledge. Then triage what you find:

• A term misheard the same way throughout (a name rendered as a consistent non-word) — propose one find-and-replace.
• A garbled clause that context can recover — propose your reading as a question ("I think this is X — does that match?"), don't just rewrite it.
• A stretch where several words are nonsense and context doesn't pin it down — flag it as garbled and leave the original; don't fabricate a clean version.

Surface the flags as a list and let the user confirm; each correction is context for the rest of the pass. A dedicated audit can go further — building a domain glossary, wrapping unrecoverable spans in callouts that preserve the original — but this much is useful on its own.

Offer to structure a long transcript

Raw output is one unbroken block of text. For anything long, offer to make it navigable: break it into paragraphs at natural shifts in topic, and add brief subheadings that summarize each section. This doesn't change the words, so it's worth doing even on a transcript you don't correct — keep it separate from the error pass.

Switching models

Follow the "Swapping models later" section of references/setup.md. It re-checks the landscape, installs the replacement, and updates the config; the staging area is untouched.