Render Complex Emojis with FFmpeg Drawtext

Rendering complex emojis—such as flag ligatures, skin tone modifiers, and Zero Width Joiner (ZWJ) sequences like the family emoji (👨‍👩‍👧‍👦)—in videos using FFmpeg’s drawtext filter can be challenging. This article provides a straight-to-the-point guide on how to successfully render these complex characters. You will learn how to configure your FFmpeg command, ensure proper font selection, and handle the text-shaping requirements necessary to display multi-codepoint emojis in full color.

Prerequisite: Verify FFmpeg Compilation Flags

To render complex emojis, FFmpeg’s drawtext filter relies on FreeType (for font rendering), HarfBuzz (for complex text shaping and ZWJ ligatures), and FriBidi (for bidirectional text handling).

Before proceeding, verify that your FFmpeg build has these libraries enabled. Run the following command in your terminal:

ffmpeg -version

Look for the following configuration flags in the output: * --enable-libfreetype * --enable-libharfbuzz * --enable-libfribidi

If these flags are missing, you must install a build of FFmpeg that includes them, as standard FreeType alone cannot combine multi-codepoint emojis into a single complex glyph.

Step 1: Obtain a Color Emoji Font

You must use a font file that supports color glyphs and complex layouts. TrueType (.ttf) or OpenType (.otf) formats work best.

• Linux/Android: Noto Color Emoji (NotoColorEmoji.ttf)
• macOS: Apple Color Emoji (typically handled system-wide, but copyable)
• Windows: Segoe UI Emoji (seguiemj.ttf)

For the most reliable cross-platform results with FFmpeg, download and use the Google Noto Color Emoji font.

Step 2: Write Emojis to a Text File

Passing complex emojis directly into the command line can lead to shell encoding issues, causing ZWJ characters or modifiers to break. To prevent this, write your emojis directly to a UTF-8 encoded text file.

Create a file named emoji.txt and paste your complex emojis into it:

🧑‍💻 🏳️‍🌈 👨‍👩‍👧‍👦

Step 3: Run the FFmpeg Command

Use the drawtext filter, pointing the fontfile parameter to your color emoji font, and the textfile parameter to your emoji.txt file.

Here is the exact command structure:

ffmpeg -i input.mp4 -vf "drawtext=fontfile='/path/to/NotoColorEmoji.ttf':textfile='emoji.txt':x=(w-tw)/2:y=(h-th)/2:fontsize=64" -c:a copy output.mp4

Key Parameter Breakdown

• fontfile: The absolute path to your color emoji font.
• textfile: The path to the UTF-8 text file containing the emojis.
• fontsize: Set this relatively high. Color bitmap fonts (like Noto Color Emoji) scale better when rendered at their native size or larger.
• x and y: Positions the text. The example above centers the emojis on the screen (w and h are video width/height; tw and th are text width/height).

Troubleshooting Common Issues

Emojis render in black and white (grayscale)

This occurs if your FreeType library was compiled without PNG support (since many color emoji fonts use embedded PNGs for color glyphs). Ensure your system’s libfreetype is compiled with libpng support.

Emojis are split into individual characters (e.g., 👨 👩 👧 👦 instead of 👨‍👩‍👧‍👦)

This indicates that HarfBuzz text shaping is not being utilized by FFmpeg. Double-check your FFmpeg build to ensure --enable-libharfbuzz is active. Additionally, make sure you are not using the text parameter with improper shell escaping; stick to textfile to ensure UTF-8 sequences remain intact.