open-whisper transcribe does what the video window does, from a terminal: you give it a file or a YouTube link, and it prints the transcript. Use it in scripts, or when you transcribe often and prefer typing. This page shows the everyday uses; Command reference has every option and exit status.
What it is for
- Turning a recording into text or subtitles without opening a window.
- Feeding a transcript to another program, in JSON with the time of each sentence and, if you ask, of each word.
- Running the same transcription again with the same options.
The command is part of the app: there is nothing else to install. It reads your settings (the video window's Speed and Model, and the Language) as its defaults, and never changes them. It never writes a file, and dictation keeps working while it runs.
Getting the command
Mac
If you installed with Homebrew, open-whisper is already on the PATH. If you installed from the .dmg, link it once. On a Mac with Apple Silicon:
ln -s "/Applications/Open Whisper.app/Contents/MacOS/open-whisper" /opt/homebrew/bin/open-whisper
On an Intel Mac, link it into /usr/local/bin/open-whisper instead. Check it in Terminal:
open-whisper --version
It prints open-whisper followed by the version. With no arguments, open-whisper starts the menu-bar app instead.
Windows
The installer adds Open Whisper's folder to your user PATH. Open a new Command Prompt or PowerShell window after installing (one that was already open does not see the change), then check it:
open-whisper --version
It prints open-whisper followed by the version. open-whisper runs open-whisper.com, the console version of the app, so the terminal waits for it and shows its output. With no arguments it stops with a usage error: the app itself starts from the Start menu.
If your PATH was already very long, the installer leaves it alone. Run the command by its full path then: open-whisper.com in the folder where Open Whisper was installed, usually %LOCALAPPDATA%\Open Whisper.
Put a path with spaces in quotes. A relative path is read from the folder the terminal is in.
Recipes
1. A file to text
open-whisper transcribe lecture.mov > lecture.txt
The text is the same as the video window's Copy with Text: a short header, then the transcript. Any file the video window accepts works here too; see Video and files.
2. Subtitles
open-whisper transcribe lecture.mov --format srt > lecture.srt
open-whisper transcribe lecture.mov --format vtt > lecture.vtt
The files are the same ones the window's Save writes.
3. JSON for another program
open-whisper transcribe lecture.mov --format json > lecture.json
The full text is in transcript.text, each sentence with its start and end in transcript.segments, and the settings used in settings. New fields may appear over time; existing ones keep their names.
4. The time of each word
open-whisper transcribe lecture.mov --format json --words > lecture.json
Each segment gains a words list, with each word's start, end and a confidence from 0 to 1. Use it to cut pauses or false starts inside a sentence. It only works with --format json, and only for a transcription made on this device: captions have no word times.
5. Numbers as they were said
open-whisper transcribe narration.wav --numbers spoken --format json > narration.json
By default the engine writes numbers as figures ("310"). With --numbers spoken it writes them in words, as spoken, and no figure appears anywhere. Useful for checking a narration against its script. A Roman numeral is made of letters and may stay as it is, and next to a number the engine sometimes slips in a short extra word. It only applies on this device, not to captions.
6. Names it gets wrong
open-whisper transcribe lecture.mov --prompt "Fabricio, Entringer, DevOps" > lecture.txt
--prompt gives the engine the spellings of names and jargon, for this call only. List the words; do not write a sentence. A file's name never influences its transcript, so this is the only way to hint a file.
7. Pinning the language
open-whisper transcribe lecture.mov --lang en > lecture.txt
Pinning the language spoken in the recording is more accurate than auto-detect. --lang auto detects it. The codes are those of the 16 languages in Settings: pt, en, es, fr, de, it, nl, ru, zh, ja, ko, ar, hi, pl, tr, uk. Any other code is a usage error.
8. A YouTube link
open-whisper transcribe "https://www.youtube.com/watch?v=VIDEO_ID" > video.txt
open-whisper transcribe "https://www.youtube.com/watch?v=VIDEO_ID" --on-device > video.txt
Put the link in quotes. Without --on-device, the command uses the video's captions when there are usable ones, which takes seconds. With --on-device, it downloads the audio and transcribes it on the computer; that flag is your consent, like the choice in the window. A video with no usable captions and no --on-device stops with exit status 7. Links need yt-dlp, as in the video window.
9. A different model or speed
open-whisper transcribe lecture.mov --model medium-q5_0 --quality accurate > lecture.txt
The model must already be on the computer: the command never downloads one, and stops with exit status 4 if it is missing. Download it in Settings or in the video window (Models). --model small-q5_1, the bundled model, always works.
What comes out where
- The result goes to standard output, and nothing else: complete, then the command ends with status 0. On any failure it stays empty, so a half transcript never reaches your file.
- Everything else goes to standard error: progress lines that start with
open-whisper:, the one-line reason when it fails, and the engine's own messages. Its wording may change, and it is safe to discard.
Read the output only when the status is 0. To see the status of the last command:
Mac
echo $?Windows
In Command Prompt, echo %ERRORLEVEL%. In PowerShell, $LASTEXITCODE.
Each status has its own meaning (4 is a missing model, 5 an unsupported format, 7 a video that needs --on-device…). The whole table, with what to do for each, is in Command reference.
The network
- A file on your computer uses no network at all.
- A YouTube link uses the network only to fetch the video. Before it fetches anything, the command says so on standard error:
open-whisper: fetching the video from the network — the transcription itself stays on this machine.
Timing and stopping
On a Mac with Apple Silicon and the bundled model, an hour of audio takes about three minutes; the first call also spends a second or two loading the model. A link with usable captions returns in seconds.
To stop, press CtrlC. The command ends within about two seconds, with status 130, and delivers nothing.