How do I let Gemini CLI transcribe audio and video?

Add the KolWrite MCP server with one gemini mcp add command. Gemini CLI can then transcribe local recordings into text, SRT subtitles or translations, billed per second to your KolWrite credits.

Get an API key Quickstart Supported languages

Last updated: · Markdown

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

Run this where KOLWRITE_API_KEY is set; -s user makes it available in every project:

gemini mcp add -s user -e KOLWRITE_API_KEY="$KOLWRITE_API_KEY" kolwrite npx -y https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz

Or add it by hand to ~/.gemini/settings.json. Gemini CLI expands $KOLWRITE_API_KEY from your environment:

{
  "mcpServers": {
    "kolwrite": {
      "command": "npx",
      "args": [
        "-y",
        "https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz"
      ],
      "env": {
        "KOLWRITE_API_KEY": "$KOLWRITE_API_KEY"
      }
    }
  }
}

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).

Check it with /mcp inside Gemini CLI.

Keep the rule in GEMINI.md

So Gemini CLI also knows the API when it writes code, add this line to GEMINI.md in the project:

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 Gemini CLI:

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

JobModelCost
A 30-minute interview, plain textbaseUS$0.24
A one-hour meeting with speaker labelsoracleUS$1.56
A one-hour Hebrew talk with English subtitlesoracleUS$1.44
One hour of noisy, overlapping audiooracle_maxUS$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

Is the key written into settings.json?

Not with the $KOLWRITE_API_KEY form: Gemini CLI reads the value from your environment when it starts the server. gemini mcp add -e stores the value you pass.