FFmpeg struggles to render specific characters when burning subtitles because the default font lacks support for those glyphs. This results in missing text, boxes, or incorrect symbols appearing on the video. To fix this, you must specify a font file that contains the necessary character sets using the
fontfile option in the
drawtext filter.
Understanding the Root Cause
When you use the
drawtext filter to burn subtitles into a video stream, FFmpeg relies on system fonts or explicitly provided font files to render the text. The default behavior often points to a generic font like "Sans" or "Helvetica," which typically only supports basic Latin characters. If your subtitle content includes accented letters, Cyrillic, Chinese, Japanese, emojis, or other special symbols, the rendering engine cannot find the visual representation for these characters. Consequently, it either skips them entirely or displays a placeholder box.
This issue is not related to the encoding of the input file but rather to the font resources available to FFmpeg at runtime. It is a common pitfall for editors working with multilingual content or creative text overlays. Without explicit guidance, FFmpeg does not attempt to download or search for alternative fonts dynamically. You must manually provide the correct font path and ensure the font supports the required Unicode range.
Solution 1: Using the Fontfile Option
The most reliable method to resolve character rendering issues is to point FFmpeg directly to a TrueType Font (TTF) or OpenType (OTF) file that supports your target language. This approach gives you full control over the appearance and compatibility of the rendered text.
First, locate a suitable font file on your system. For example, on Linux systems, fonts are often stored in
/usr/share/fonts/. On Windows, they are usually in
C:\Windows\Fonts\, though you may need to copy the
.ttf file to your working directory for easier access.
Next, modify your FFmpeg command to include the
fontfile parameter within the
drawtext filter expression. Here is an example command structure:
ffmpeg -i input.mp4 -vf "drawtext=text='Hello World':fontsize=24:fontfile=/path/to/font.ttf:x=10:y=10" output.mp4
In this command, replace
/path/to/font.ttf with the absolute path to your chosen font file. Absolute paths are preferred because relative paths can be ambiguous depending on where you execute the command from. Ensure the path is accessible by the user running FFmpeg.
If you are using SubRip (
.srt) files with the
subtitles filter instead of
drawtext, the process is slightly different. The
subtitles filter allows you to set the font via the
force_style option inside the filter complex.
ffmpeg -i input.mp4 -vf "subtitles=file.srt:force_style='FontName=/path/to/font.ttf'" output.mp4
This ensures that the subtitle renderer uses the specified font for all glyphs defined in the SRT file.
Solution 2: Checking Font Encoding and Availability
Even with a valid font file, issues can persist if the font itself is corrupted or if the file permissions prevent FFmpeg from reading it. Always verify that the font file is not empty and has read permissions. On Linux, you can check permissions using
ls -l /path/to/font.ttf.
Additionally, some older fonts may not support modern Unicode standards. If you are dealing with complex scripts like Arabic or Devanagari, ensure the font supports shaping and ligatures. Fonts like "Noto Sans" from Google are excellent choices because they cover nearly all Unicode characters, making them ideal for global projects.
It is also crucial to escape special characters in your text string if you are hardcoding it into the filter. Characters like colons, commas, and backslashes have special meanings in FFmpeg filter expressions. Use backslashes to escape them, or wrap the text in single quotes if the syntax allows, to prevent parsing errors that might mimic rendering failures.
For more information on handling subtitles in different languages, see
Making Switchable Subtitles and Black Video with FFmpeg: A Solution.
Solution 3: Debugging Rendering Failures
If the text still does not appear correctly, enable verbose logging to diagnose the issue. Run FFmpeg with the
-v debug flag to see detailed output regarding font loading and glyph selection. Look for messages indicating "Could not find font" or "Glyph not found."
You can also test the font independently by converting a simple text image to verify its capabilities. Use tools like ImageMagick or online font viewers to confirm that the font displays the problematic characters correctly. This step isolates whether the problem lies with FFmpeg or the font file itself.
Another debugging technique is to simplify the filter expression. Start with a minimal command that renders a single ASCII character, then gradually add more complex characters. This helps identify exactly which symbol causes the failure. Once identified, you can determine if a different font variant is needed.
If you are extracting frames for analysis, refer to
Extracting Frames from a Video using FFmpeg to inspect the output visually frame-by-frame.
Frequently Asked Questions
Why do I see boxes instead of characters?
Boxes indicate that the font file being used does not contain a glyph for the specific character in your subtitle. You must switch to a font that supports the Unicode range of those characters, such as Noto Sans or Arial Unicode MS.
Can I use a font from my system without specifying the path?
Not reliably. While some systems allow FFmpeg to search standard directories, it is best practice to always provide the absolute path to the
fontfile to avoid ambiguity and ensure consistent results across different machines.
Does the subtitles filter support custom fonts?
Yes, the
subtitles filter supports custom fonts through the
force_style option. You can specify the
FontName property within the style string to point to a specific TTF or OTF file.
How do I handle emoji in burned-in subtitles?
Emojis require a font with comprehensive emoji support. Standard system fonts often lack recent emoji updates. Use dedicated emoji fonts like "Apple Color Emoji" or "Segoe UI Emoji" and ensure the
fontfile points to them correctly.
What if the font file is too large?
Large font files can slow down processing time, especially for high-resolution videos. Consider using a subsetted font that only includes the characters you need, or choose a lightweight font family to improve performance during rendering.