How to

Transcribe a video with Whisper for free

vid2context transcribes any video or audio file with Whisper-class models and never charges you for it. It tries, in order: Whisper on your machine, hosted free tiers with your own key, and keyless hosts that need no account at all. Paid services are used only when you set their key.

Transcribe a file with no setup

From a clone of the repo, with no keys set:

sh
git clone https://github.com/nirholas/vid2context.git
cd vid2context
npm install
npm run -s cli -- tests/fixtures/media/apollo11-small-step.mp3 --timestamps

That file is Neil Armstrong's first words on the Moon (public domain, 24.112688 seconds). This is the transcript the keyless OVH whisper-large-v3-turbo rung returned for it, recorded from the real service and rendered by vid2context:

text
[0:00] I'm going to step off the limb now.
[0:07] That's one small step for man, one giant leap for mankind.

Detected language: en. MP3 and WAV work as they are; other audio and video formats need ffmpeg installed so the audio can be extracted. Links work too: for a YouTube video with captions, add --mode stt to skip the captions and transcribe the audio instead.

Keyless, no account

These rungs need nothing:

ovh whisper-large-v3-turbo

Keyless hosts allow only a few requests per minute per IP, and they receive your audio. When one rate-limits, the chain cools it down and moves on. Set VID2CONTEXT_KEYLESS=0 to never use them.

Free tiers with your own key

A free key is faster and has higher limits. Each of these is free to sign up for:

  • stt/cloudflare-binding/@cf/openai/whisper-large-v3-turbo: set CLOUDFLARE_AI_BINDING
  • stt/cloudflare-binding/@cf/openai/whisper: set CLOUDFLARE_AI_BINDING
  • stt/cloudflare/@cf/openai/whisper-large-v3-turbo: set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN
  • stt/cloudflare/@cf/openai/whisper: set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN
  • stt/groq/whisper-large-v3-turbo: set GROQ_API_KEY
  • stt/mistral/voxtral-mini-transcribe-3: set MISTRAL_API_KEY

Put the key in .env at the repo root (every key is optional; .env.example lists them all).

On your own machine

Local rungs run first and send nothing anywhere:

  • stt/local: set LOCAL_STT_BASE_URL and LOCAL_STT_MODEL
  • stt/transformers/onnx-community/whisper-base: set TRANSFORMERS_STT_MODEL
  • stt/whisper-cpp: set WHISPER_CPP_MODEL

The quickest is whisper.cpp: npx tsx providers/stt-whisper-cpp/src/setup.ts installs the official binary (checksum verified), downloads a model, and prints the env lines to add. To make sure nothing ever leaves your machine, set VID2CONTEXT_POLICY=local-only.

Long files

Hosted rungs cap upload size (Groq takes 25 MB per file), so long audio is split into chunks, transcribed, and joined back with correct timestamps. MP3 and WAV split without extra tools; other formats split with ffmpeg.

Where the transcript goes

Raw transcripts are always kept. Ask for any format with --format (text, json, markdown, srt, vtt, pack), or hand the file to your agent through the MCP server, which accepts local file paths too.

Updated 2026-11-14Edit on GitHubView as Markdown