How to Use the FFmpeg Eval Filter

This article provides a practical guide on how to use the evaluation (eval) engine and the eval parameter within FFmpeg filters. You will learn the difference between initialization and per-frame evaluation, how to implement dynamic mathematical expressions, and see real-world examples utilizing audio and video filters.

In FFmpeg, many filters allow you to use mathematical formulas to calculate values dynamically. The eval option dictates when these formulas are calculated. It typically accepts two values:

  • init: Evaluates the expression only once, when the filter is first loaded. This is highly efficient and ideal for static values.
  • frame: Re-evaluates the expression for every single video frame or audio sample. This is necessary for creating dynamic, time-based animations, fades, and transitions.

1. Dynamic Audio Volume Control

The volume audio filter utilizes the eval parameter to adjust volume levels dynamically over time. By setting eval=frame, FFmpeg recalculates the volume expression for every incoming audio frame.

To modulate volume in a periodic wave (using a sine wave based on time t):

ffmpeg -i input.mp3 -af "volume=volume='1+0.5*sin(2*PI*t)':eval=frame" output.mp3

In this command:

  • t represents the current time in seconds.
  • The volume oscillates between 0.5 and 1.5 times the original volume.
  • eval=frame ensures the sine wave formula is continuously calculated.

2. Moving Text with the Drawtext Filter

The drawtext filter is commonly used to overlay text onto a video. Setting eval=frame allows you to animate the text's coordinate positions (x and y) frame by frame.

To scroll text horizontally across the screen:

ffmpeg -i input.mp4 -vf "drawtext=text='Scrolling Text':x='t*100':y='h-50':eval=frame" output.mp4

In this command:

  • x='t*100' moves the text to the right by 100 pixels per second.
  • y='h-50' keeps the text statically positioned 50 pixels from the bottom of the video frame.
  • eval=frame tells FFmpeg to recalculate the x position on every frame.

3. Pixel-Level Manipulation with the GEQ Filter

The Generic Equation (geq) filter evaluates math expressions for every individual pixel in a frame. While it does not use a literal eval toggle, it inherently operates on a per-frame, per-pixel evaluation basis.

To increase the intensity of the red channel based on the pixel's X-coordinate:

ffmpeg -i input.mp4 -vf "geq=r='r(X,Y)*(X/w)':g='g(X,Y)':b='b(X,Y)'" output.mp4

In this command:

  • X and Y represent the coordinates of the current pixel.
  • w represents the width of the frame.
  • The red channel (r) progressively brightens from the left side of the screen to the right.