This is the full reference for the open-whisper command. To get started with it, and to put it on your PATH, see Command line. Options, streams, the JSON fields and the exit statuses are stable: new ones may be added, existing ones are never renamed or renumbered.
Synopsis
open-whisper transcribe <INPUT> [--format txt|srt|vtt|json] [--on-device] [--words] [--prompt <text>]
[--numbers written|spoken] [--model <id>] [--quality fast|balanced|accurate]
[--lang <code>|auto]
open-whisper --help | -h
open-whisper --version
<INPUT>is one media file or one video link per call. A path that exists is a file; anything else must be a link to a single YouTube video. Put quotes around a path with spaces.- Options may come before or after the input, as
--option valueor--option=value.--ends the options. --versionprintsopen-whisperand the version, such asopen-whisper 0.1.0.- The command reads the preferences you set in the app and never changes them.
Mac
With no arguments, open-whisper starts the menu-bar app instead.
Windows
With no arguments, open-whisper stops with a usage error (status 2): the app itself starts from the Start menu. The command works in Command Prompt and PowerShell.
Options
| Option | Values | Default | What it does |
|---|---|---|---|
--format | txt, srt, vtt, json | txt | The output format (see below). |
--on-device | none | off | For a link: skip the captions and transcribe the audio on this computer. This flag is your consent, never assumed. A file is always transcribed on this computer. |
--words | none | off | With --format json only: each segment gets a list of words with their times. Captions carry no word times. |
--prompt | text | none | A vocabulary hint (names, jargon) for this call. For a link it replaces the hint taken from the title and channel. An empty value means no hint. |
--numbers | written, spoken | written | spoken writes numbers in words, as said, with no figures. Roman numerals are letters and may stay. Applies only to what is transcribed on this computer, not to captions. |
--model | small-q5_1, base, medium-q5_0, large-v3-turbo-q5_0 | the video model set in the app | The model for this call. It must already be downloaded: the command never downloads (status 4). |
--quality | fast, balanced, accurate | the video speed set in the app | The speed for this call. |
--lang | pt, en, es, fr, de, it, nl, ru, zh, ja, ko, ar, hi, pl, tr, uk, or auto | the Language set in the app | The language for this call. An unknown code is status 2. Pinning the language usually gives better results than auto. |
small-q5_1 is the bundled model. The others are downloaded once in the app: see Models.
Output formats
| Format | What you get |
|---|---|
txt | Plain text, with a header (title, channel, publication date, duration, link or file, language, source) and a paragraph break wherever speech pauses for more than 2 seconds. |
srt | Subtitles (SRT), with no header. |
vtt | Subtitles (WebVTT), with the header as a NOTE block. |
json | One JSON document with the transcript, its segments and how it was made (see below). |
txt, srt and vtt are identical, byte for byte, to what Copy and Save give in the video window.
The two streams
- Standard output carries only the result, in UTF-8 with
\nline endings. It is written in full, then the command exits with status 0. On any failure it is empty, so a script never mistakes a message for a transcript. - Standard error carries everything else, for people: a line before any network use (links only), progress, and one line explaining a failure. These lines may change; don't parse them.
- Standard input is ignored.
Some standard error lines you may see:
open-whisper: fetching the video from the network — the transcription itself stays on this machine
open-whisper: captions found (manual, pt) — using them; pass --on-device to transcribe the audio instead
open-whisper: transcribing on-device with small-q5_1 (accurate)
open-whisper: no speech detected
open-whisper: interrupted; nothing was delivered
The JSON envelope
With --format json, standard output holds one JSON document. Fields are added over time but never removed or renamed, so ignore fields you don't know.
| Field | What it holds |
|---|---|
app | name and version. |
input | kind (file or url), reference (the path or link), title, duration_secs, and for a file audio (sample rate, channels, track, container, codec). |
settings.model | The model id, and origin: preferences or override (you passed --model). |
settings.quality | value and origin. |
settings.language | requested, origin, and detected (the language heard). |
settings.prompt | value and origin: override, video_metadata or none. |
settings.numbers | value, and applied: true when transcribed on this computer, false for captions. |
transcript.provenance | on_device, manual_captions or automatic_captions. |
transcript.language | The transcript's language. |
transcript.repetition_flagged | true when excessively repeated passages were trimmed. |
transcript.segments | Each with start_ms, end_ms, text; words with --words; suspect: true on a line that looks like a channel sign-off. |
transcript.text | The whole text. |
transcript.empty_reason | no_speech, only when no segment is left. The status is still 0. |
transcript.suppressed | Segments set aside as not speech, each with start_ms, end_ms, text and reason (silence, subtitle_credit or no_speech). Present only when there are some. |
transcript.word_timestamps | With --words: whether word times are available. For captions, available: false with reason: captions. |
Each item in words has start_ms, end_ms, text and probability. The words, in order, are the segment's text split on spaces. Each lasts at least 40 ms, words never overlap and they stay inside their segment. probability goes from 0 to 1 and is relative, not a calibrated score.
Exit statuses
| Status | Meaning | What to do |
|---|---|---|
| 0 | The transcript is on standard output. Also when no speech was found (see empty_reason). | Read standard output. |
| 1 | Internal error. | Report it with the standard error line. |
| 2 | Usage error: unknown option or value, missing or extra input, unknown --lang or --model, an input without transcribe, a link that isn't a single YouTube video. | Fix the command. open-whisper --help shows the usage. |
| 3 | yt-dlp is missing or too old (links only). | Install or update yt-dlp: see Troubleshooting. |
| 4 | The model isn't downloaded. | Use --model small-q5_1, or download the model in the app. |
| 5 | Unsupported format. The message names the codec or container. | Export as MP4 or M4A with AAC, or as MP3, FLAC or WAV. |
| 6 | The file can't be read: no file there, a folder, no permission, empty or truncated, no audio track, or longer than 3 hours. | Fix the input. |
| 7 | The link has no usable captions and you didn't pass --on-device. | Run again with --on-device. |
| 8 | Video error: unavailable, private or removed, age-restricted, not available in your region, a live stream, rate-limited, no network, a decoding or transcription failure, an unrecognised failure, or another video already running. | Rate limits and network errors are worth retrying later. |
| 9 | The transcript was ready, but standard output closed before receiving it. | Run again. |
| 130 | Interrupted (CtrlC). The command stops within 2 seconds and delivers nothing. | Nothing to do. |
Mac
Read the status in Terminal with echo $?.
Windows
Read the status with echo %ERRORLEVEL% in Command Prompt, or $LASTEXITCODE in PowerShell.
Guarantees
- The command never writes a file, whatever happens. Redirect standard output to save the result.
- The input file is read where it is. Its size and modification date don't change.
- A file from your computer makes no network request at all. A link uses the network only to fetch the video.
- It never changes your preferences, and dictation keeps working while it runs.
- One input per call. There are no folders, wildcards or playlists: loop over files in your own script.
- It doesn't read subtitle tracks inside a file, choose an audio track, stream partial output, translate or summarise.
On a Mac with Apple Silicon, the bundled model transcribes roughly 20 to 25 times faster than real time, so an hour of audio takes about 3 minutes, plus a second or two to load the model. On Windows the speed depends on the processor. In a script, allow at least a tenth of the recording's length plus 60 seconds before timing out.
open-whisper transcribe "lecture.mov" --format srt > lecture.srt
open-whisper transcribe "https://youtu.be/VIDEO_ID" --on-device --format json > video.json