Open Whisper Docs

Appendix A3 Command reference

Reading time · 7 min

The complete open-whisper transcribe command: every option, the formats, the two streams, the JSON fields and every exit status.

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 value or --option=value. -- ends the options.
  • --version prints open-whisper and the version, such as open-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

OptionValuesDefaultWhat it does
--formattxt, srt, vtt, jsontxtThe output format (see below).
--on-devicenoneoffFor 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.
--wordsnoneoffWith --format json only: each segment gets a list of words with their times. Captions carry no word times.
--prompttextnoneA 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.
--numberswritten, spokenwrittenspoken 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.
--modelsmall-q5_1, base, medium-q5_0, large-v3-turbo-q5_0the video model set in the appThe model for this call. It must already be downloaded: the command never downloads (status 4).
--qualityfast, balanced, accuratethe video speed set in the appThe speed for this call.
--langpt, en, es, fr, de, it, nl, ru, zh, ja, ko, ar, hi, pl, tr, uk, or autothe Language set in the appThe 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

FormatWhat you get
txtPlain 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.
srtSubtitles (SRT), with no header.
vttSubtitles (WebVTT), with the header as a NOTE block.
jsonOne 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 \n line 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.

FieldWhat it holds
appname and version.
inputkind (file or url), reference (the path or link), title, duration_secs, and for a file audio (sample rate, channels, track, container, codec).
settings.modelThe model id, and origin: preferences or override (you passed --model).
settings.qualityvalue and origin.
settings.languagerequested, origin, and detected (the language heard).
settings.promptvalue and origin: override, video_metadata or none.
settings.numbersvalue, and applied: true when transcribed on this computer, false for captions.
transcript.provenanceon_device, manual_captions or automatic_captions.
transcript.languageThe transcript's language.
transcript.repetition_flaggedtrue when excessively repeated passages were trimmed.
transcript.segmentsEach with start_ms, end_ms, text; words with --words; suspect: true on a line that looks like a channel sign-off.
transcript.textThe whole text.
transcript.empty_reasonno_speech, only when no segment is left. The status is still 0.
transcript.suppressedSegments 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_timestampsWith --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

StatusMeaningWhat to do
0The transcript is on standard output. Also when no speech was found (see empty_reason).Read standard output.
1Internal error.Report it with the standard error line.
2Usage 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.
3yt-dlp is missing or too old (links only).Install or update yt-dlp: see Troubleshooting.
4The model isn't downloaded.Use --model small-q5_1, or download the model in the app.
5Unsupported format. The message names the codec or container.Export as MP4 or M4A with AAC, or as MP3, FLAC or WAV.
6The 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.
7The link has no usable captions and you didn't pass --on-device.Run again with --on-device.
8Video 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.
9The transcript was ready, but standard output closed before receiving it.Run again.
130Interrupted (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