How to use the Whisper speech transcription agent skill

What the Whisper skill makes the agent do

An agent skill is a folder containing a SKILL.md file of instructions that Claude loads when a request matches the skill. Once this one is installed, the agent knows how to run OpenAI's Whisper model on your recordings.

According to the skill, the agent can transcribe speech in 99 languages, translate non-English speech into English, identify the language, pick a model size based on speed and accuracy needs, add word-level timestamps, and export results as TXT, SRT, VTT or JSON. It also covers batch processing many files and faster-whisper for quicker results.

Install the Whisper skill

Download the ZIP of the skill from this page and unzip it. You can install it in one of two ways.

For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal (all projects): ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder

Install the software the skill needs

The skill's scripts run Whisper locally, so your machine needs Python and a few packages. The skill lists Python 3.8-3.11 and the openai-whisper package. It also needs ffmpeg installed on the system, which the skill says to install with brew, apt or choco depending on your OS.

Install the Python package with the command below, then install ffmpeg using the command for your operating system.

• Python 3.8-3.11 is required
• ffmpeg must be on the system (macOS: brew install ffmpeg; Ubuntu: sudo apt install ffmpeg; Windows: choco install ffmpeg)
• Optional: faster-whisper and a CUDA GPU for faster processing
• Optional: LangChain, only for the document loader example

Trigger the skill with natural requests

You do not need to name the skill. Ask for the outcome in plain language, and mention the file and the output you want. Requests that match the skill's use cases include transcribing a podcast, making subtitles for a video, translating a Spanish recording into English, or turning meeting audio into notes.

Name the model or format if you have a preference, such as a turbo model or an SRT file. Otherwise the agent will choose sensible defaults from the skill guidance.

• "Transcribe episode12.mp3 and give me the text."
• "Make an SRT subtitle file for interview.mp4."
• "Translate spanish-call.mp3 into English text."
• "Transcribe these 20 lecture recordings and save each as a txt file."

Choose a model size

The skill lists six models from tiny (39M parameters) to large (1550M parameters), plus turbo (809M). Smaller models run faster and use less memory. Larger models are generally more accurate but slower. The skill recommends turbo for the best balance of speed and quality, and base for prototyping.

Only tiny, base, small and medium have English-only variants in the skill's table. Large and turbo are multilingual only.

• tiny: 39M, about 1 GB VRAM
• base: 74M, about 1 GB VRAM
• small: 244M, about 2 GB VRAM
• medium: 769M, about 5 GB VRAM
• turbo: 809M, about 6 GB VRAM
• large: 1550M, about 10 GB VRAM

Safety, privacy and limits

The skill runs scripts on your machine and says it uses the network, so review what the agent is running before you approve it. The Whisper transcription itself runs locally. If you add a managed service such as AssemblyAI, Deepgram or Google Speech-to-Text, which the skill lists as alternatives, your audio is sent to that provider.

The skill also documents limits. Accuracy degrades on audio longer than about 30 minutes, so split long recordings into chunks. The model can hallucinate, repeating or inventing text. It has no speaker identification, and it is not suited to live captioning, though faster-whisper streaming is briefly covered.

• Keep sensitive recordings local, and avoid cloud alternatives unless you accept the data transfer
• Split recordings longer than about 30 minutes
• Check transcripts for invented or repeated text
• Quality varies by language and accent, and with background noise

Tips for better transcripts

Specifying the language is faster than auto-detect. An initial prompt with technical terms or proper nouns can improve accuracy on specialised content. A GPU speeds up processing considerably; the skill notes 10-20x faster on GPU.

Converting audio to WAV can improve compatibility. For video, the skill shows extracting audio with ffmpeg before transcribing.

• Specify the language when you know it
• Add an initial prompt with names and jargon
• Batch process multiple files
• Use a GPU if available