Guide · Agent skill

How to use the OpenAI Whisper Transcription agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The openai-whisper-api skill lets an AI agent turn an audio recording into a text transcript by sending the file to OpenAI's Audio Transcriptions endpoint, which runs Whisper. It is aimed at people who have meeting, interview or voice-memo recordings to convert, and at developers who want a simple shell-based transcription step in an agent workflow. By the end of this guide you will know what the skill does, how to install it, how to give it an API key, how to ask for a transcript in plain language, and what data leaves your machine.

OpenAI Whisper Transcriptionspinabot/brigade · MIT Download the skill

Quick start

1Check curl. Confirm that curl is installed on the machine where the skill will run.
2Get an OpenAI API key. Create or sign in to an OpenAI account with API access and generate an API key.
3Provide the key. Set OPENAI_API_KEY in your environment, or add an apiKey entry under skills and openai-whisper-api in the Brigade config file.
4Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, then Capabilities, then Skills.
5Ask for a transcript. Ask the agent in plain language and give the path to your m4a or ogg file.
6Choose options. Add --out, --language, --prompt or --json if you need a specific output path, language hint, context or format.
7Review the output. Open the .txt file, or the JSON file if you used --json, and check the transcript against the recording.

What does the openai-whisper-api skill make the agent do?

An agent skill is a folder of instructions and scripts that an AI agent can load when a task matches the skill's description. This one covers audio transcription. Once it is installed, the agent can take an audio file such as an m4a or ogg recording and produce a text transcript using OpenAI's speech-to-text service.

By default the result is saved as a .txt file next to the input, and the model used is whisper-1. The skill can also save the output as JSON when asked. You can give it hints such as the language or speaker names to help accuracy.

How do you install the skill?

The skill ships as a ZIP file, which you can download from this page. Unzip it into one of these locations: ~/.claude/skills/ to make it available across your projects, or the .claude/skills/ folder inside a specific project to limit it to that project.

If you use the Claude apps instead, you can upload the ZIP under Settings, then Capabilities, then Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/ folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before it works?

The skill needs curl, a command-line tool, on the machine where the script runs. It also needs an OpenAI account with API access and an OpenAI API key. The key can come from the OPENAI_API_KEY environment variable or from an apiKey entry in the Brigade config file.

Setting the key in the config file looks like this. The file is $BRIGADE_CONFIG_PATH, or ~/.brigade/brigade.json by default.

curl (command-line tool)
OPENAI_API_KEY environment variable, or apiKey in the Brigade config file
An OpenAI account with API access
Optional: OPENAI_BASE_URL for an OpenAI-compatible proxy or local gateway

{
  skills: {
    "openai-whisper-api": {
      apiKey: "OPENAI_KEY_HERE",
    },
  },
}

How do you transcribe a recording?

The simplest way is to ask the agent in plain language, for example: "Transcribe this interview at /path/to/audio.m4a." The agent uses the skill's script, which runs against the file you point to.

You can also run the script yourself. Pass the path to the audio file and the transcript is written to <input>.txt by default.

{baseDir}/scripts/transcribe.sh /path/to/audio.m4a

Which options can you use?

The script accepts a few flags. Use --out to choose the output path, --model to pick a model (the default is whisper-1), --language to give a language hint, --prompt to pass context such as speaker names, and --json to save JSON instead of plain text.

--out sets the output file path
--model sets the model; the default is whisper-1
--language gives a language hint, for example en
--prompt passes context such as speaker names
--json saves the result as JSON

{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt "Speaker names: Peter, Daniel"
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json

What about privacy, network use and safety?

The skill runs a script and needs network access. The audio file is uploaded to OpenAI for processing, or to the gateway you set in OPENAI_BASE_URL if you use one. Anything in the recording is therefore shared with that service. Do not use this skill for confidential or sensitive recordings unless you are comfortable with that.

The skill is not suitable for offline or air-gapped environments, because it cannot reach the transcription endpoint without a network connection. Each transcription is billed through your OpenAI API account.

Audio leaves your machine and is processed by OpenAI or your configured gateway
Requires network access to the transcription endpoint
Your API key is needed; keep it out of shared files
Per-use API charges apply to your OpenAI account

Tips for better transcripts

Give the language when you know it, and pass speaker names or domain terms with --prompt so that names are spelled correctly. Choose a clear output path with --out so you can find the file later. Use --json when you need a structured result for another tool to read.

Pass --language when you know the spoken language
Use --prompt to supply names and specialist terms
Use --json when another tool needs to parse the result
Use a self-hosted or OpenAI-compatible proxy by setting OPENAI_BASE_URL

What people use it for

Turning a recorded meeting into a text file you can search and share
Converting interview audio into a transcript for writing or review
Transcribing voice memos into notes an agent can summarise later
Adding a transcription step to a shell-based agent workflow

Frequently asked questions

Is the openai-whisper-api skill free?

The skill is released under the MIT licence. Using it still requires an OpenAI account with API access, and each transcription is billed as per-use API usage on that account.

What do I need to install the openai whisper skill?

You need curl on your machine, an OpenAI API key, and the skill ZIP from this page unzipped into ~/.claude/skills/ or a project's .claude/skills/ folder. Optionally set OPENAI_BASE_URL if you use a proxy or local gateway.

Where do I put my OpenAI API key?

Set it as the OPENAI_API_KEY environment variable, or add it as an apiKey entry under the openai-whisper-api skill in the Brigade config file at $BRIGADE_CONFIG_PATH, which defaults to ~/.brigade/brigade.json.

Which audio formats can it transcribe?

The source names m4a and ogg as examples of accepted audio. Check the OpenAI speech-to-text documentation linked from the skill for the full list of supported formats.

Can I use it offline?

No. The skill needs network access to the transcription endpoint, so it will not work in offline or air-gapped environments.

Is this skill safe for private recordings?

Not by default. The audio is uploaded to OpenAI, or to whichever gateway OPENAI_BASE_URL points to, so avoid it for confidential material unless you accept that third party processing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you need recordings turned into text quickly, you already have an OpenAI API account, or you want a simple shell-based transcription step in an agent workflow. Pick something else if your recordings are confidential, you cannot send audio to a third-party API, or you need to work offline.

Download the skill