How to Use FFmpeg sendcmd Filter with a Command File

This article explains how to write and format a command file for the FFmpeg sendcmd and asendcmd filters. You will learn the exact syntax rules, how to structure time intervals, and how to apply these commands to dynamically alter video and audio filter parameters during playback or processing.

The sendcmd filter reads a list of commands from a text file or direct string and passes them to other filters in the filtergraph at specified timestamps. This allows you to dynamically change parameters—such as text content, volume, position, or crop factors—without splitting the video into multiple segments.

1. Syntax of the Command File

The command file is a plain text file where each line defines a time trigger, a target filter, the command name, and the arguments.

The basic syntax for a single command line is:

[time] [target] [command] [arguments];

Syntax Breakdown:

• [time]: The exact time or time range when the command triggers.
  • Single timestamp: 5.0 (triggers exactly at 5 seconds).
  • Time range: 5.0-10.0 (triggers at 5 seconds, and can revert or apply a different state at 10 seconds depending on the filter’s behavior).
  • Format: Can be expressed in seconds (e.g., 12.34) or as HH:MM:SS.milli (e.g., 00:01:15.500).
• [target]: The specific filter to control.
  • Use the filter name (e.g., drawtext).
  • To target a specific instance of a filter, use filter_name@instance_name (e.g., drawtext@title).
• [command]: The command supported by the target filter. For most filters, this is reinit to reinitialize parameters.
• [arguments]: The parameters you want to change, formatted as key=value pairs. Multiple parameters must be separated by colons : or commas , depending on the filter’s syntax.
• ; (Semicolon): Every command line must end with a semicolon.
• # (Comments): Any line starting with # is ignored by FFmpeg.

2. Example of a Command File

Below is an example of a command file named commands.txt. It targets a drawtext filter with the instance name mytext to change the text content and its vertical position at different timestamps.

# Change the text to "Intro" at 2 seconds
2.0 drawtext@mytext reinit text='Intro':y=100;

# Move the text lower and change content at 5 seconds
5.0 drawtext@mytext reinit text='Main Segment':y=300;

# Change the text to "Outro" at 10 seconds
10.0 drawtext@mytext reinit text='Outro':y=100;

3. Running the FFmpeg Command

To use the command file, you must reference it using the f parameter in the sendcmd filter. You must also assign the corresponding instance name (using @name) to the filter you want to control.

Here is the FFmpeg command line structure:

ffmpeg -i input.mp4 -vf "sendcmd=f=commands.txt,drawtext@mytext=text='Default':x=100:y=100:fontfile=font.ttf:fontsize=24:fontcolor=white" -c:a copy output.mp4

How this command works:

1. -vf "sendcmd=f=commands.txt,... tells FFmpeg to load the triggers from commands.txt.
2. drawtext@mytext defines an instance of the drawtext filter named mytext.
3. As the video processes, the sendcmd filter intercepts the timestamps specified in commands.txt and updates the parameters of drawtext@mytext in real-time.