How do I let Codex transcribe audio and video?
Add four lines to ~/.codex/config.toml (or run codex mcp add), or put the kolwrite-transcribe skill in ~/.agents/skills. Codex can then turn recordings in your repository into text, SRT subtitles or translations, billed per second to your KolWrite credits.
What you do once
Create the account and the key yourself at console.kolwrite.com: sign up, add credits, then open API Keys and create a key. An agent cannot do this for you.
Put the key in your shell profile (~/.zshrc, ~/.bashrc) so every agent session you start can read it, then open a new terminal:
export KOLWRITE_API_KEY=... # paste the key from API Keys
The tools read the key only from this variable. Do not paste it into a chat or commit it to a repository.
Add the MCP server
In ~/.codex/config.toml. env_vars passes KOLWRITE_API_KEY from the shell you start Codex in, so the key is not written into the file:
[mcp_servers.kolwrite]
command = "npx"
args = ["-y", "https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz"]
env_vars = ["KOLWRITE_API_KEY"]
Or with one command (this stores the key in config.toml):
codex mcp add kolwrite --env KOLWRITE_API_KEY="$KOLWRITE_API_KEY" -- npx -y https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz
The server gives the agent six tools: transcribe_file, transcribe_url, upload_file, get_job, list_models, list_languages. It runs on your computer with Node.js 18 or newer and is fetched from https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz (SHA-256 0dcd6ff169b860b9363044837b8545279efa585c4987b20d81035f920f6ac7ca).
Or install the agent skill
Codex reads skills from ~/.agents/skills (every project) or .agents/skills in the repository:
mkdir -p ~/.agents/skills && cd ~/.agents/skills
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip && rm kolwrite-transcribe.zip
If a new skill does not appear, restart Codex.
Keep the rule in AGENTS.md
So every Codex session in the repository knows the API without a tool, add this line to AGENTS.md:
For speech-to-text use the KolWrite API; read https://console.kolwrite.com/agent-instructions.md before writing code. The key is in KOLWRITE_API_KEY.
What to ask
Three things to ask Codex:
Transcribe ~/Downloads/interview.m4a with KolWrite and save the text as interview.txt next to it.
Make English SRT subtitles for talk.mp4 with KolWrite, one cue per sentence.
Who said what in team-call.mp3? Transcribe it with speaker labels on the oracle model, then list each speaker's action items.
What it costs
| Job | Model | Cost |
|---|---|---|
| A 30-minute interview, plain text | base | US$0.24 |
| A one-hour meeting with speaker labels | oracle | US$1.56 |
| A one-hour Hebrew talk with English subtitles | oracle | US$1.44 |
| One hour of noisy, overlapping audio | oracle_max | US$3.60 |
Billed per second of audio from your credits, with no minimum. Speaker labels add 0.10 credits per audio hour. The MCP server and kolwrite.py pick base unless you or the agent name another model, and oracle_mini when translating. Full rates: /models.
What the agent must not do
- Ask you for the key in the chat, print it, or write it into a file, a command or a commit.
- Start the same transcription again after a timeout or a network error. Each start is a new job that is billed; it should check the job instead, or ask you.
- Type timestamps itself. To cut or quote by time it takes segment numbers from the transcript and computes the times in code from the word timings.
- Send a YouTube or other web page address as the media. It needs the media file itself.
- Transcribe long recordings (over an hour) without telling you the expected cost first.
Questions and answers
Does this work in the Codex IDE extension too?
The extension reads the same ~/.codex/config.toml, so the MCP server is available there as well.
Can Codex write code that calls the API in my app?
Yes. Point it at agent-instructions.md and openapi.json; the MCP server is for transcribing files while you work, not a library for your app.