How to Use Custom Fonts with FFmpeg Subtitles

This article explains how to specify a custom font directory when using the subtitles or ass video filters in FFmpeg. You will learn how to use the native fontsdir filter option, how to handle path escaping, and how to use Fontconfig environment variables as an alternative fallback method. This ensures your subtitles render with the correct custom typefaces without needing to install them system-wide.

The easiest way to specify a custom font directory is to use the fontsdir parameter, which is built directly into both the subtitles and ass video filters in FFmpeg.

Syntax for subtitles filter:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:fontsdir=/path/to/custom/fonts" output.mp4

Syntax for ass filter:

ffmpeg -i input.mp4 -vf "ass=subs.ass:fontsdir=/path/to/custom/fonts" output.mp4

FFmpeg will scan the specified directory for TrueType (.ttf) and OpenType (.otf) fonts and make them available to the subtitle renderer.

Handling Special Characters and Windows Paths

FFmpeg uses the colon (:) as a separator for filter arguments. If your font directory path contains a colon (common in Windows drive letters like C:\), you must escape it.

Windows Example (Escaping the Colon):

On Windows, escape the drive letter colon with a backslash, or wrap the path in single quotes and escape the colon:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:fontsdir='C\:/Users/Name/Fonts'" output.mp4

Alternatively, use relative paths to avoid using drive letters entirely:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:fontsdir=./local_fonts" output.mp4

Method 2: Using the FONTCONFIG_FILE Environment Variable

If you are using an older version of FFmpeg that does not support the fontsdir parameter, or if you need to manage complex font fallback rules, you can use Fontconfig. This method works on Linux, macOS, and Windows builds compiled with Fontconfig support.

  1. Create a custom configuration file (e.g., fonts.conf) in your project folder with the following XML content:
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
    <!-- Point to your custom fonts directory -->
    <dir>/path/to/custom/fonts</dir>
    
    <!-- Fallback to system cache -->
    <cachedir>/var/cache/fontconfig</cachedir>
</fontconfig>
  1. Set the environment variable to point to your custom configuration file when running your FFmpeg command:

On Linux / macOS:

FONTCONFIG_FILE="/path/to/fonts.conf" ffmpeg -i input.mp4 -vf "subtitles=subs.srt" output.mp4

On Windows (Command Prompt):

set FONTCONFIG_FILE=C:\path\to\fonts.conf
ffmpeg -i input.mp4 -vf "subtitles=subs.srt" output.mp4