How to Burn WebVTT Subtitles into Video Using FFmpeg

Burning WebVTT (.vtt) subtitles directly into a video—also known as hardcoding—embeds the text permanently onto the video frames so they cannot be disabled. This guide explains how to use FFmpeg's subtitles video filter to burn WebVTT files into your video, configure standard encoding options, handle file path escaping, and customize font styling using force_style.

Prerequisites

To burn subtitles using FFmpeg, your FFmpeg build must be compiled with the libass library enabled (--enable-libass). You can verify this by running:

ffmpeg -version

Look for --enable-libass in the output configuration list.

Basic Command

The subtitles filter takes the path to your .vtt file and renders the text directly onto the video frames. Because the video stream is modified, it must be re-encoded.

ffmpeg -i input.mp4 -vf "subtitles=subtitles.vtt" -c:v libx264 -crf 23 -c:a copy output.mp4

Breakdown of Arguments:

  • -i input.mp4: Specifies the input video file.
  • -vf "subtitles=subtitles.vtt": Applies the subtitle filter using the specified WebVTT file.
  • -c:v libx264: Re-encodes the video stream using the H.264 video codec.
  • -crf 23: Sets the Constant Rate Factor for video quality (lower values mean higher quality; 18–28 is typical for x264).
  • -c:a copy: Copies the audio stream without re-encoding, preserving quality and saving processing time.
  • output.mp4: The output file containing the hardcoded subtitles.

Handling File Paths and Special Characters

FFmpeg's filtergraph parser requires special handling for specific characters like colons, backslashes, and commas in file paths.

On Linux and macOS:

If your subtitle file contains special characters or spaces, wrap the path or escape colons:

ffmpeg -i input.mp4 -vf "subtitles='my subtitles.vtt'" -c:v libx264 -c:a copy output.mp4

On Windows:

Windows drive letters contain colons (e.g., C:\path\sub.vtt), which conflict with FFmpeg filter options. Escape the colon with a backslash and replace backslashes with forward slashes:

ffmpeg -i input.mp4 -vf "subtitles='C\:/path/to/subtitles.vtt'" -c:v libx264 -c:a copy output.mp4

Customizing Subtitle Appearance

You can override the default text styling by passing ASS (Advanced SubStation Alpha) style parameters to the force_style option within the filter.

ffmpeg -i input.mp4 -vf "subtitles=subtitles.vtt:force_style='FontName=Arial,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BorderStyle=1,Outline=1,Shadow=1,MarginV=25'" -c:v libx264 -c:a copy output.mp4

Common force_style Attributes:

  • FontName: Specifies the font family (e.g., Arial, Roboto).
  • FontSize: Defines the size of the text.
  • PrimaryColour: The fill color of the text in &HAABBGGRR (Alpha, Blue, Green, Red) hexadecimal format (e.g., &H00FFFFFF is opaque white, &H0000FFFF is opaque yellow).
  • OutlineColour: The color of the text border in &HAABBGGRR format.
  • Outline: The thickness of the border around the text (e.g., 1 or 2).
  • Shadow: The depth of the drop shadow.
  • MarginV: The vertical margin from the bottom or top of the frame in pixels.