To fix FFMPEG subtitle font issues, you must ensure the font file is accessible to the process and correctly referenced in the
drawtext filter. Common failures stem from relative path errors or missing system font caches. This guide details how to configure absolute paths, verify font availability, and resolve rendering jitter often caused by recent library updates.
Understanding the Drawtext Filter Requirements
The
drawtext video filter is the standard method for overlaying text onto video streams in FFMPEG. However, it does not automatically search your operating system's default font directories for security and consistency reasons. If you simply specify a font name like
fontname=Arial, FFMPEG may fail to locate it unless it is explicitly installed in a location the binary can read, or if you provide the full path to the font file.
The syntax generally follows this structure:
-vf "drawtext=text='Hello World':fontfile=/path/to/font.ttf:fontsize=24"
Notice the use of
fontfile instead of
fontname. While
fontname attempts to match against known system fonts,
fontfile points directly to the .ttf or .otf file. This distinction is critical when working with custom fonts that are not part of the core OS installation. Without the correct file path, the filter defaults to a fallback font, which often results in garbled characters or completely missing subtitles.
Resolving Path and Accessibility Issues
One of the most frequent causes of font failure is using relative paths that break depending on where the command is executed. For example, running a script from
/home/user/videos while the font resides in
/home/user/fonts requires careful navigation. It is highly recommended to use absolute paths to eliminate ambiguity. You can obtain the absolute path by navigating to the directory in your terminal and typing
pwd (print working directory) combined with the filename.
Additionally, permissions play a significant role. The user account executing the FFMPEG command must have read access to the font file. If you are running the command via a web server or a cron job, the context user might be
www-data or
nobody, neither of which may have permission to read your personal home directory fonts. Ensure the font file has at least read permissions (
chmod 644 font.ttf) for all users.
If you are embedding this logic within a Python script using libraries like
subprocess or
ffmpeg-python, ensure that the environment variables are not interfering with font discovery. Sometimes, setting the
FONTCONFIG_FILE or
FONTCONFIG_PATH environment variables can help direct FFMPEG to a specific configuration if you are relying on system-wide font resolution rather than direct file paths.
Addressing Rendering Jitter and Libharfbuzz
Even when the font loads correctly, you might encounter visual artifacts such as jittering, misalignment, or incorrect kerning. Recent versions of FFMPEG have updated their dependency on
libharfbuzz for advanced text shaping. Changes in this library can sometimes cause rendering jitter, especially with complex scripts or non-Latin characters.
If you experience this issue, check your version of FFMPEG and its dependencies. You can diagnose this by running
ffmpeg -version and looking for the
libharfbuzz version number. If you are using a very recent build, consider checking if there are known issues with your specific combination of OS and library version. In some cases, downgrading to a stable release or updating to the latest patch version resolves the jitter.
You can also try disabling advanced text shaping features if they are not strictly necessary for your language. While
drawtext handles basic Latin characters well out of the box, complex scripts may require additional flags or pre-processing of the text string into glyphs. For simple English subtitles, sticking to standard TrueType fonts without exotic ligatures usually avoids these complications entirely.
For more information on handling video output issues, see our article on
Troubleshooting: Unable to Display FFMPEG-Created Video in HTML.
Verifying Font Installation and Cache
Before running your FFMPEG command, verify that the font is actually usable by the system. On Linux, you can use the
fc-list command to list available fonts. Search for your specific font family to ensure it is recognized by the fontconfig system. If
fc-list | grep Arial returns nothing, the font is not installed in the system directories.
Installing fonts typically involves copying them to
/usr/local/share/fonts/ or
~/.local/share/fonts/ and then running
fc-cache -fv to rebuild the cache. After refreshing the cache, re-run your FFMPEG command. This step is crucial because FFMPEG often relies on the system font cache for resolving
fontname attributes. Without an updated cache, even correctly installed fonts may appear invisible to the filter.
If you are creating images or short clips for testing, refer to our guide on
FFMpeg Image Creation from Timestamps to quickly preview your subtitle styling before processing full-length videos.
Advanced Troubleshooting Steps
If standard methods fail, try isolating the problem by simplifying the command. Start with a minimal
drawtext filter using a known good font file path. Gradually add back complexity, such as positioning (
x=...,
y=...), coloring, and shadow effects. This incremental approach helps identify if a specific parameter is causing the conflict.
Also, consider the character encoding of your input text. If you are passing text from a file or a variable, ensure it is UTF-8 encoded. Mismatched encodings can lead to square boxes or question marks appearing in place of characters, which mimics font errors but is actually an encoding issue. Use tools like
iconv to convert text files to UTF-8 if necessary.
For those dealing with complex timeline edits, understanding how filters interact is vital. See
Going round in circles with ffmpeg concat and filter_complex to better manage filter chains that include subtitle overlays.
Frequently Asked Questions
Why does my subtitle disappear after a few seconds?
This usually happens if the duration of the
drawtext filter is not synchronized with the audio track. Ensure you are using the
start and
end parameters within the filter to define exactly when the text should appear and disappear, matching your subtitle timing data.
Can I use OTF fonts instead of TTF?
Yes, FFMPEG supports OpenType Font (.otf) files just as well as TrueType (.ttf). Simply point the
fontfile parameter to your .otf file. However, note that some older versions of FFMPEG had limited support for advanced OpenType features, so stick to standard glyph rendering if you encounter issues.
How do I center the text horizontally?
You can use the expression
x=(w-text_w)/2 within the
drawtext filter. This calculates the horizontal position based on the width of the video frame (
w) minus the width of the text itself, effectively centering it regardless of the text length.
What if I get a 'Font not found' error despite providing a path?
Check that the path is absolute and that the file exists at that exact location. Also, verify that the file extension matches what FFMPEG expects (usually .ttf or .otf) and that the file is not corrupted. Try opening the font in a local image editor to confirm it is valid.
Does FFMPEG support Unicode characters in subtitles?
Yes, provided your system has the appropriate fonts installed and the input text is UTF-8 encoded. You must use a font that contains the glyphs for the characters you wish to display. Standard ASCII characters will work with almost any font, but emojis or CJK characters require specialized fonts.