Render RTL Text in FFmpeg with Drawtext Filter

This article explains how to successfully render right-to-left (RTL) text, such as Arabic, Hebrew, or Persian, using the FFmpeg drawtext filter. You will learn the essential library requirements, the configuration needed to prevent reversed or disconnected lettering, and practical command-line examples to overlay RTL text onto your videos.

The Core Requirement: Libfribidi

By default, FFmpeg's drawtext filter processes text from left to right. To correctly render RTL languages, which require proper text direction and character shaping (ligatures), your FFmpeg build must be compiled with the libfribidi library enabled.

To verify if your FFmpeg installation supports this, run the following command in your terminal:

ffmpeg -version

Look through the configuration block in the output. If you see --enable-libfribidi, your version of FFmpeg is ready. If it is missing, you must download a build that includes it or compile FFmpeg from source with the --enable-libfribidi flag.

Basic Command Syntax

Once you have verified libfribidi support, you can overlay RTL text using the drawtext filter. You must also use a font that natively supports the target RTL character set.

Here is a basic command template:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/RTL-compatible-font.ttf:text='your RTL text here':fontcolor=white:fontsize=24:x=(w-text_w)/2:y=(h-text_h)/2" -codec:a copy output.mp4

Key Parameters:

  • fontfile: The absolute path to a TrueType (.ttf) or OpenType (.otf) font that supports your language (e.g., Amiri or Noto Sans Arabic for Arabic, David or Rubik for Hebrew).
  • text: The actual RTL string you want to render.
  • x and y: The coordinates for text placement. The example above centers the text on the screen.

Recommended Method: Using a UTF-8 Text File

Typing RTL text directly into a command-line terminal often leads to encoding issues or cursor direction confusion. The safest and most reliable method is to write your RTL text into a UTF-8 encoded text file and reference it in the command.

  1. Create a text file named subtitle.txt and save your RTL text inside it using UTF-8 encoding.
  2. Run the following FFmpeg command:
ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/RTL-compatible-font.ttf:textfile=subtitle.txt:fontcolor=white:fontsize=32:x=(w-text_w)/2:y=h-100" -codec:a copy output.mp4

Using the textfile parameter ensures that the character sequence is read exactly as intended by the text editor, allowing libfribidi to handle the shaping and bidirectional rendering correctly.

Troubleshooting Common RTL Issues

  • Letters are reversed (left-to-right instead of right-to-left): This occurs if your FFmpeg build lacks libfribidi. You must obtain an FFmpeg build compiled with --enable-libfribidi.
  • Letters are separated/disconnected (Arabic/Persian): This happens when the font renderer cannot apply ligatures. Ensure your font file fully supports complex text layout, and check that libharfbuzz (often paired with libfribidi) is also enabled in your FFmpeg build.
  • Text appears as boxes or question marks: The selected font file does not contain the glyphs for the language you are trying to render. Switch to a Unicode font that explicitly supports your specific RTL script.