FFmpeg Custom Font Path for Subtitles and ASS

This article explains how to configure a custom font path when rendering subtitles using the subtitles and ass filters in FFmpeg. You will learn how to use the built-in fontsdir parameter, set up Fontconfig environment variables, and apply custom fonts to your video overlay processing.

The easiest way to specify a custom font directory in modern versions of FFmpeg is by using the fontsdir option directly inside the video filter (-vf). This option tells the underlying libass library where to look for your TrueType (.ttf) or OpenType (.otf) font files.

To use this method, define the directory containing your fonts in the filter argument:

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

For ASS subtitle files, the syntax is identical:

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

Note: Replace /path/to/custom/fonts with the absolute path to the folder where your font files are stored.

Method 2: Using Fontconfig Environment Variables

If you are using an older version of FFmpeg that does not support the fontsdir parameter, or if you need to manage a more complex font configuration, you can use Fontconfig environment variables. FFmpeg’s subtitle filters rely on Fontconfig to locate system fonts.

Step 1: Create a custom fonts.conf file

Create a text file named fonts.conf and define your custom font directory inside it:

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
    <dir>/path/to/custom/fonts</dir>
</fontconfig>

Step 2: Set the environment variable

Before running your FFmpeg command, point the FONTCONFIG_FILE environment variable to your custom configuration file.

On Linux/macOS:

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

On Windows (Command Prompt):

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

On Windows (PowerShell):

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

Forcing a Specific Font in SRT Subtitles

When using the subtitles filter with SRT files, you can force the filter to use a specific font name from your custom directory by using the force_style parameter. The font name must match the internal name of the font file (not necessarily the filename).

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