How to Burn ASS Subtitles into Video with FFmpeg

This guide explains how to use the ass video filter in FFmpeg to permanently burn SubStation Alpha (SSA/ASS) subtitles into a video file. You will learn the basic command-line syntax, how to handle system fonts, and how to resolve common path-escaping issues to ensure your stylized subtitles render correctly on the output video.

Prerequisites

Before using the ass filter, your version of FFmpeg must be compiled with the libass library. You can verify this by running the following command in your terminal:

ffmpeg -version

Look for --enable-libass in the configuration block of the output. If it is missing, you will need to download a build of FFmpeg that includes libass or compile it with this flag enabled.

The Basic Command

To burn an external .ass subtitle file into a video, use the -vf (video filter) option followed by the ass filter name and the path to your subtitle file.

ffmpeg -i input.mp4 -vf "ass=subtitles.ass" output.mp4

Here is what each part of the command does: * -i input.mp4: Specifies the input video file. * -vf "ass=subtitles.ass": Applies the video filter named ass using subtitles.ass as the source. * output.mp4: The resulting video file with the subtitles permanently written into the video frames.

Handling File Paths and Escaping

FFmpeg’s filter engine requires special escaping for certain characters in file paths, such as colons (:) and backslashes (\). This is especially common on Windows systems.

If your subtitle path contains spaces or drive letters, you must escape them. Wrap the path in single quotes and escape backslashes and colons:

ffmpeg -i input.mp4 -vf "ass='C\:/path/to/subtitles.ass'" output.mp4

Alternatively, to avoid escaping issues, place the subtitle file in the same directory as your terminal session and use a simple relative path like ass=subtitles.ass.

Managing Subtitle Fonts

The ass filter relies on Fontconfig to locate the fonts specified in your .ass file. If a font is missing from your system, Fontconfig will fall back to a default font (usually Arial or Sans), which will change the appearance of your subtitles.

To ensure fonts render correctly: 1. Install the fonts: Install all unique fonts used by the subtitle file onto your operating system’s default font directory. 2. Using local fonts: If you do not want to install fonts globally, you can set the FONTCONFIG_FILE environment variable to point to a custom local configuration file that defines where your fonts are stored.