subthis documentation

1. Install

subthis needs two things on your computer: uv (which installs subthis and Python itself) and ffmpeg (which reads the audio out of video files). Both are one command per OS.

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
winget install --id Gyan.FFmpeg -e
uv tool install subthis

Open a new PowerShell window after installing uv so the command is found.

macOS (Terminal)

curl -LsSf https://astral.sh/uv/install.sh | sh
brew install ffmpeg
uv tool install subthis

If Homebrew is missing, install it first from brew.sh.

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt install ffmpeg   # or dnf / pacman, per your distribution
uv tool install subthis

2. First run

subthis setup

The first run is a one-time wizard. Every screen is shown below exactly as it appears in the terminal, with what it is for, what each line means, and what to do. On most machines it takes about two minutes, two presses of Enter, and one paste.

Screen 1: welcome

╭───────────────────────────────╮
│ Welcome to subthis  ·  v1.8.4 │
╰───────────────────────────────╯

subthis turns a video into subtitles. This one-time setup takes about
two minutes. Nothing on your computer is changed except subthis's own
settings folder: ~/.config/subthis

Purpose: tell you what is about to happen. Nothing on your computer changes except subthis's own settings folder, whose path is on the last line. Nothing to do here.

Screen 2: the ffmpeg check

  ✓ ffmpeg is installed (subthis uses it to read the sound from your videos)

Purpose: confirm that ffmpeg, the program that reads the sound out of a video, is installed. A green check means you are fine. If you see this instead:

  ! A helper program called ffmpeg is missing. It reads the sound from videos.
    To install it: sudo apt install ffmpeg
    Then run 'subthis setup' again.

Screen 3: why you need an OpenAI key

subthis sends your video's audio to OpenAI (the company behind ChatGPT)
to turn the speech into text. For that you need your own OpenAI key:
a long code starting with sk- that acts like a password. It is saved
only on this computer.

Purpose: explain the mechanism. The audio goes to OpenAI to turn speech into text, which needs your own API key, a long code starting with sk- that works like a password and stays on your computer. If a key is already saved from an earlier run you will see A key is already saved. Press Enter at the prompt below to keep it. instead of the next screen, and an empty Enter keeps it.

Screen 4: opening the key page

Here's what happens next:
  1. OpenAI's key page opens in your browser. No account yet? The site
     will have you sign up first (same login as ChatGPT, and it's quick).
  2. On the key page, click 'Create new secret key', give it any name,
     click 'Create secret key', then 'Copy'. It is shown only this once.
  3. Come back here and paste it.

Press Enter to open the key page in your browser... 

Purpose: get a key. The three numbered lines describe what will happen, and the last line waits for Enter to open OpenAI's key page in your browser. If the browser does not open by itself, this is the address: platform.openai.com/api-keys

Screen 5: pasting and testing the key

Paste your OpenAI key here and press Enter: sk-••••••••••••
  Checking your key with OpenAI...
  ✓ The key works and your account has credit.

Purpose: make sure the key works before saving it. Paste the key (Ctrl+V, right-click and paste, or Ctrl+Shift+V in some terminals) and press Enter. subthis sends OpenAI one tiny request, costing a fraction of a cent, because only a real request reveals an account without credit. Two green checks mean the key is valid and the account has credit. Three other outcomes are possible:

  ✗ OpenAI does not accept this key. It may be mistyped, expired,
    or revoked. Copy a fresh one from:
    https://platform.openai.com/api-keys
Paste your OpenAI key here and press Enter: 

  ✗ The key itself works, but the account behind it has no credit yet.
    The transcription service is prepaid, like a phone card. In the
    billing page that opens next:
      1. Click 'Add payment method' and enter your card details.
      2. Click 'Add to credit balance' and choose 5 dollars (the
         minimum; it covers roughly five hours of video).
      3. If it offers auto-reload, you can switch that off.
    Press Enter to open the billing page... 
    Press Enter once your balance shows the credit, and it will be checked again... 

  ! Could not reach OpenAI to test the key (network is unreachable).
    Saving it anyway. subthis will say so clearly if it turns out not to work.

Screen 6: saving, and the terms file

  ✓ Key saved to ~/.config/subthis/.env
  ✓ Created a terms file at ~/.config/subthis/terms.txt
    (optional: list names and jargon there and subthis will spell them right)

Purpose: report what was saved. The first line is where the key went. The second says an empty terms file was created, where you can later list names and jargon so subthis spells them right (see Teach it terms). Optional, nothing to do now. If the file already existed you see Keeping your existing terms file instead.

  ! The 'subthis' command is not reachable from new terminals yet. To fix:
    installed with uv:   run  uv tool update-shell
    installed with pipx: run  pipx ensurepath
    then open a new terminal window.

Screen 7: done

╭─────────────────╮
│ You're all set! │
╰─────────────────╯

To make subtitles, type subthis, a space, and then your video file:
    subthis ~/Videos/lecture.mp4
Tip: type "subthis " and drag the video from your files into this
window, then press Enter. The subtitles are saved as an .srt file
next to the video.

Purpose: say you are done and show how to use it. Type subthis, a space, then the path of your video. The tip: after the space you can drag the video file from your file manager into the terminal window and the path is pasted for you. Enter starts the job, and the .srt file lands next to the video. Continue with Make subtitles.

An OPENAI_API_KEY environment variable, if set, overrides the stored key; the wizard warns about it on the first screen. To replace a key later: subthis config key.

3. Make subtitles

This is the whole basic use: type subthis, a space, the video file, and press Enter.

subthis lecture.mp4

The easy way to get the path right: type subthis  (with the space) and drag the video file from your file manager into the terminal window. The full path is pasted for you. Then Enter. This is what it looks like:

$ subthis lecture.mp4
Transcribing your video...
  still working on your video (1m00s so far)...

  ✓ Done! 214 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt

Line by line: Transcribing your video... means the audio is on its way to OpenAI. While you wait, a still working line shows up now and then with the elapsed time, just so you know it is alive; count on about a minute per ten minutes of speech. At the end: how many subtitles were made, and below it the full path of the .srt file. It is saved next to the video, with the same name.

A long video is cut into parts automatically, each part is transcribed on its own, and the result is merged into one file. In the terminal that looks like this:

$ subthis lecture.mp4
Long video: 3 parts of up to 20 minutes each. Each part takes roughly a minute per 10 minutes of speech.
Transcribing part 1 of 3...
Transcribing part 2 of 3...
Transcribing part 3 of 3...

  ✓ Done! 1,180 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt

If a subtitle file with that name already exists, subthis does not overwrite it quietly. It stops:

$ subthis lecture.mp4
subthis: Output already exists: /home/dana/Videos/lecture.srt. Use --force to replace it.

Now drag the .srt into your video editor (Premiere Pro, DaVinci Resolve, Final Cut Pro, CapCut, or any other editor that imports SRT) or a video player. How are the captions made? Each part goes to OpenAI twice, once for the most accurate wording and once for the timing of every word, and subthis aligns the two. You do not need to understand this to use it.

4. Teach it terms

Terms are names and phrases subthis should spell correctly and keep in English inside Hebrew speech: companies, products, people, jargon. The syntax is the same everywhere: spaces separate terms, and single quotes group a multi-word term.

Terms for one run

subthis clip.mp4 --term "Omarchy 'Wispr Flow'"

These apply to this run only. --term can be repeated in the same command.

Saved terms for every video

$ subthis config terms "Omarchy 'Wispr Flow'"
  ✓ Added 2 term(s) to ~/.config/subthis/terms.txt:
    Omarchy
    Wispr Flow
  These now apply to every video you transcribe.

The terms are appended to the saved terms file (its path is on the first line) and apply to every video from now on. With no argument, subthis config terms opens an interactive editor listing your saved terms, with a key guide at the bottom of the screen: arrows move, space selects, m marks or unmarks all, r removes the selected terms after a confirmation, a adds new ones, q saves and quits. It ends with Saved N term(s) to ….

Per-folder terms

Put a file named subthis-terms.txt next to your videos and it is picked up automatically for any video in that folder. One term per line. Spelling corrections use aliases: the correct name, an equals sign, then the wrong forms separated by a vertical bar.

MyCompany
DaVinci Resolve = דה וינצ'י ריזולב | Davinci Resolve

When such a file is found, subthis says so at the start of the run:

$ subthis clip.mp4
Using the terms from /home/dana/Videos/subthis-terms.txt
Transcribing your video...

5. Options and settings

There are two kinds. Command-line options affect one run only: add them after the file name. Persistent settings are saved once with subthis config and apply to every video after that.

Options for one run

-o, --output

Where to save the subtitle file. Without it the file goes next to the video with the same name. A folder that does not exist is created.

$ subthis talk.mp4 -o subs/talk.srt
Transcribing your video...

  ✓ Done! 96 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/subs/talk.srt

--max-words 1|2|3

The most words allowed in one caption. Default 3 (or whatever you set with config captions words). 2 gives shorter, punchier captions that suit vertical video; 1 shows one word at a time. The terminal output is the same as a normal run.

subthis clip.mp4 --max-words 2

--language

Which languages to expect in the speech, as two-letter codes (he Hebrew, en English, ru Russian, ar Arabic, and so on). The default is Hebrew and English together, so most of the time you do not need this flag. Repeat it for each extra language.

subthis clip.mp4 --language he --language ru

--force

Replace an existing subtitle file. Without the flag subthis stops with Output already exists (see Make subtitles).

subthis lecture.mp4 --force

--term

Terms for this run only. Explained in Teach it terms.

--terms-file

Use a different terms file instead of the saved one. Handy when a client or project has its own list.

subthis clip.mp4 --terms-file ~/clients/acme-terms.txt

--version, help, docs

subthis --version prints the version. subthis help (or subthis alone) prints the full help. subthis docs opens this documentation in the browser.

Persistent settings

Running subthis config with nothing after it lists the four subcommands:

$ subthis config
subthis: Usage:
  subthis config key     change your saved OpenAI key
  subthis config terms   review, add, and remove your saved terms
  subthis config terms "term 'multi word term'"   add terms directly
  subthis config open on|off   open the folder when subtitles are done
  subthis config captions      view and tune caption timing and style

subthis config key

Replace the saved OpenAI key, for example after the old one was revoked. It opens the key page in the browser, waits for the paste, and checks the new key exactly like the first run does (validity and credit) before saving. For safety the key is not accepted as a command-line argument, only pasted at the waiting prompt.

$ subthis config key
Let's replace your saved OpenAI key. Copy the new one from:
    https://platform.openai.com/api-keys
Paste your OpenAI key here and press Enter: sk-••••••••••••
  Checking your key with OpenAI...
  ✓ The key works and your account has credit.
  ✓ New key saved to ~/.config/subthis/.env

subthis config terms

Edit the saved terms. Explained in Teach it terms.

subthis config open on|off

Whether to open the file manager with the subtitle file selected when a run finishes, in addition to printing the path. Off by default. Without on or off the command only shows the current state:

$ subthis config open
Opening the folder when done is currently: off
Turn it on or off with: subthis config open on   (or off)

$ subthis config open on
  ✓ subthis will now open the folder with your file when it finishes.

From now on every run ends with one more line, and the file manager opens:

  ✓ Done! 214 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt
  Opening its folder...

subthis config captions

This is where you shape how captions look and are timed. The defaults follow subtitle-industry standards (Netflix's guidelines, for example), and most people never need to touch them. With no arguments it lists everything: the setting's name, its current value, whether that is the default or changed, and a short description.

$ subthis config captions
Caption settings (change one with: subthis config captions <name> <value>):

  words        3        (default)  words per caption line, 1 to 3
  pause        0.5      (default)  a silence this long (seconds) starts a new line
  hang         0.5      (default)  how long a line stays after its last word (seconds)
  min          0.83     (default)  minimum time a line stays on screen (seconds)
  gap          0        (default)  empty space kept between one line and the next (seconds)
  punctuation  remove   (default)  'remove' cleans captions, 'keep' leaves punctuation in
  silence      hold     (default)  'hold' keeps a line up until the next one starts (captions connect), 'cut' ends it after the hang time

  reset        put everything back to the defaults

What each setting means:

Change one setting with a name and a value. It is saved and applies to every video from now on:

$ subthis config captions words 2
  ✓ Saved: words = 2. This applies to every video from now on.

A name without a value shows that one setting:

$ subthis config captions words
words is 2  (words per caption line, 1 to 3)
Change it with: subthis config captions words <value>

An invalid value is rejected with an explanation. Times must be a number of seconds between 0 and 10:

$ subthis config captions pause fast
subthis: pause must be a number of seconds, like 0.5

And to put every setting back to the defaults at once:

$ subthis config captions reset
  ✓ Caption settings are back to the defaults.

All persistent settings live in subthis's settings folder (~/.config/subthis on Linux and macOS, %APPDATA%\subthis on Windows). Deleting the folder resets everything, including the key.

6. Updates

At the start of an interactive run, subthis checks PyPI (three-second budget, silent when offline). If a newer version exists it asks once. Answer yes and it updates itself and reruns your exact command; answer no and it prints the command to update later. On Windows the running program cannot replace itself, so subthis prints the command for you to run in a fresh window:

uv tool upgrade subthis

7. Troubleshooting

"subthis: command not found" after installing

Run uv tool update-shell (or pipx ensurepath), then open a new terminal window.

"OpenAI no longer accepts your saved key"

The key was revoked or deleted. Run subthis config key and paste a fresh key from platform.openai.com/api-keys.

"Your OpenAI account is out of credit"

Add credit at the billing page (5 dollars minimum) and run subthis again.

"Required command not found: ffmpeg"

Install ffmpeg for your OS (see Install), then rerun. subthis setup prints the exact command for your system.

"The video may have no audio track"

The file has no sound to transcribe. Check it plays with audio in a media player.

8. CLI reference

Exit codes: 0 success, 1 a handled error (message on stderr, prefixed subthis:), 130 cancelled with Ctrl+C.

9. For AI agents

If you are an AI agent operating a computer for a user: subthis is non-interactive-safe. Piped stdin disables all prompts, colors, and browser openings; the update check is skipped when stdin is not a TTY, and can be disabled explicitly with SUBTHIS_SKIP_UPDATE=1. The canonical machine-readable summary is at https://subthis.webivize.com/llms.txt, and the full docs as markdown at https://subthis.webivize.com/docs.md.

# minimal agent flow
uv tool install subthis
OPENAI_API_KEY=sk-... subthis input.mp4 -o output.srt --force
# stdout ends with the absolute path of the written file