Last updated: May 29, 2025

<span aria-hidden="true" id="cli-subtitle-workflow-generate-convert-and-burn"></span>

# CLI subtitle workflow: generate, convert, and burn

![Tim Koschützki](/assets/images/teammates/avatar-tim-kos-1.jpg?dpl=dpl_5zDg5SaYi7KaFpi2w3C4HPYbgapj)

#### Tim Koschützki

Co-founder · Berlin, Germany · Show bio

[](https://x.com/tim%5Fkos)[](https://github.com/tim-kos)

Managing subtitles quickly and reproducibly is key to accessible, multilingual video. Command-line interface (CLI) tools excel here because they script well, play nice with CI/CD, and avoid slow, click-heavy GUIs. This guide walks through a soup-to-nuts workflow—generate, convert, embed, or burn subtitles—using open-source utilities you can install with a single command.

<span aria-hidden="true" id="why-use-cli-tools-for-subtitle-management"></span>

## Why use CLI tools for subtitle management?

CLI programs let you:

* batch-process hundreds of videos without lifting a mouse,
* automate tasks in GitHub Actions, Jenkins, or cron jobs,
* mix and match best-in-class tools instead of relying on one monolithic app, and
* reproduce results exactly by committing your commands to version control.

If your team already ships code from the terminal, adding subtitles the same way keeps the pipeline consistent.

<span aria-hidden="true" id="generate-subtitles-with-whisper-or-subsai"></span>

## Generate subtitles with whisper or subsai

Modern speech-to-text models finally make auto-captioning accurate enough for production. OpenAI’s Whisper is the workhorse, and subsai adds a friendly wrapper plus some extra editing tricks.

<span aria-hidden="true" id="whisper"></span>

### Whisper

```bash
# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install whisper
pip install git+https://github.com/openai/whisper.git

# Generate english subtitles in SRT format
whisper video.mp4 --model base --output_format srt --language en

```

> [!Tip]
>
> * Choose `tiny` or `small` for speed, `medium` or `large` for higher accuracy.
> * Use `--device cuda` when an NVIDIA GPU is available; it cuts runtime dramatically.

<span aria-hidden="true" id="subsai"></span>

### Subsai

```bash
pip install git+https://github.com/absadiki/subsai.git

# Same result as above, with some post-processing niceties
subsai video.mp4 --model base --output subtitles.srt

```

Both tools output time-stamped subtitles that are usually 95 %–98 % accurate out of the box. A quick manual review with a subtitle editor such as Aegisub finishes the job.

<span aria-hidden="true" id="convert-between-formats-with-subtitle-edit-cli"></span>

## Convert between formats with subtitle edit CLI

Need WebVTT for the web or ASS for advanced styling? Subtitle Edit—famous for its GUI—also offers a cross-platform CLI.

```bash
# For Ubuntu/Debian, use the .Net version
sudo apt-get install -y dotnet-sdk-8.0

# Install the global tool
dotnet tool install --global SubtitleEdit.CLI

# Convert SRT ➜ VTT
SubtitleEdit.CLI convert input.srt output.vtt

# Convert SRT ➜ ASS
SubtitleEdit.CLI convert input.srt output.ass

```

Subtitle Edit supports more than 200 formats, so odds are good it speaks the one you need.

<span aria-hidden="true" id="embed-soft-subtitles-with-mkvtoolnix"></span>

## Embed soft subtitles with mkvtoolnix

Soft subtitles live in the container as a separate track. They can be toggled, styled, or replaced without touching the video stream.

```bash
# Install mkvtoolnix (Ubuntu/Debian)
sudo apt-get install mkvtoolnix

# Embed subtitles
mkvmerge -o output.mkv video.mp4 subtitles.srt

```

Want multiple languages?

```bash
mkvmerge -o output.mkv \
  video.mp4 \
  --language 0:eng subs_en.srt \
  --language 0:spa subs_es.srt

```

Players such as VLC, mpv, and most smart-TV apps will present a language picker automatically.

<span aria-hidden="true" id="burn-hard-code-subtitles-with-ffmpeg"></span>

## Burn (hard-code) subtitles with FFmpeg

Hard subtitles are painted onto the video pixels, guaranteeing 100 % compatibility at the cost of flexibility.

```bash
# Plain SRT burn-in
ffmpeg -i video.mp4 -vf "subtitles=subtitles.srt" -c:v libx264 -crf 20 -preset veryfast output.mp4

# Custom styling, white text, 24 pt font
affinity='FontSize=24,PrimaryColour=&HFFFFFF&'
ffmpeg -i video.mp4 -vf "subtitles=subtitles.srt:force_style='${affinity}'" \
       -c:v libx264 -crf 20 -preset veryfast output-styled.mp4

# Ass/ssa subtitles retain their own styling
affinity_file=subtitles.ass
ffmpeg -i video.mp4 -vf "ass=${affinity_file}" -c:v libx264 -crf 20 -preset veryfast output-ass.mp4

```

Use `-c:v h264_nvenc` or `-c:v hevc_nvenc` to leverage an NVIDIA GPU and cut encoding time.

<span aria-hidden="true" id="automate-everything-with-a-shell-script"></span>

## Automate everything with a shell script

Below is a Bash script that wires some of the previous commands together. Drop it into`subtitles.sh`, make it executable, and point it at a directory of `.mp4` files.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Create a function for processing
process_video() {
  local video="$1"
  echo "Processing ${video}..."

  # Generate subtitles
  # Whisper output is e.g. video.srt for video.mp4.
  whisper "$video" --model base --output_format srt --language en

  # Convert to VTT if needed
  # This assumes whisper created ${video%.mp4}.srt
  SubtitleEdit.CLI convert "${video%.mp4}.srt" "${video%.mp4}.vtt"

  # Create soft-subbed version
  # This also assumes ${video%.mp4}.srt exists
  mkvmerge -o "${video%.mp4}_subbed.mkv" "$video" "${video%.mp4}.srt"
}

# Process all MP4 files
for video in *.mp4; do
  process_video "$video"
done

```

Feel free to stash this in a CI job so every new video that lands in the repo gets subtitles automatically.

<span aria-hidden="true" id="performance-and-scaling-tips"></span>

## Performance and scaling tips

* **Pick the right Whisper model.** The `tiny` model processes roughly real-time on a CPU; `large`can be 10× slower but catches tricky words.
* **Use GPUs whenever possible.** Both Whisper (`--device cuda`) and FFmpeg (`-hwaccel cuda`) see 5×–10× gains on modern hardware.
* **Parallelize cautiously.** Whisper is CPU/GPU-bound, so one instance per GPU is usually optimal. Launching too many processes may slow everything down.
* **Cache results.** Store generated `.srt` files so reruns only transcode.

<span aria-hidden="true" id="soft-vs-hard-subtitles"></span>

## Soft vs. Hard subtitles

|Soft|Hard||
|-|-|-|
|Toggleable?|Yes|No|
|Multiple languages|Yes|One per file|
|Player support|Needs subtitle-aware player|Any player|
|File size impact|Negligible|Re-encode increases size|
|Editable later|Easy|Impossible|

Choose soft subtitles for streaming platforms and editing flexibility. Use hard subtitles when you cannot control the playback environment or need burnt-in branding.

<span aria-hidden="true" id="wrap-up"></span>

## Wrap-up

With Whisper, subsai, Subtitle Edit CLI, MKVToolNix, and FFmpeg you can stitch together a zero-click pipeline that adds high-quality captions to every video your team ships. If you would rather skip server maintenance altogether, our [🤖 /video/subtitle](/docs/robots/video-subtitle.md) Robot handles generation, conversion, and burn-in through a single API call. A minimalAssembly looks like:

```json
{
  "steps": {
    "subtitle_video": {
      "robot": "/video/subtitle",
      "use": ":original",
      "subtitles_type": "burned",
      "font_size": 24,
      "position": "bottom",
      "font_color": "FFFFFF",
      "border_style": "outline"
    }
  }
}

```

Give it a try—your viewers, especially those watching on muted autoplay, will thank you.

\#cli-subtitle-tools#ffmpeg#whisper#subsai#subtitle-edit-cli#mkvtoolnix#video-encoding-service

### 👩‍💻 Join 20k+ developers

Sign up for our [monthly newsletter](/newsletters.md) to receive direct links to 3 exclusive tech — and 2 product updates. No less, no more.

Your email:

Get access

## File uploading and encoding. Made simple.

Transloadit streamlines file handling for developers, trusted by brands like Coursera and The New York Times. We’re known for a reliable API, top-notch support, and a strong commitment to open source, with projects like [Uppy⁠](https://uppy.io) and [Tus⁠](https://tus.io) setting standards in file processing.

[Sign up](/c/)[Book a Demo](https://survey.typeform.com/to/kRg47Xi5)

No credit card needed · 5 GB included in the free plan

Cancel anytime