Configure Command Interval in FFmpeg sendcmd Filter

The FFmpeg sendcmd filter allows you to send commands to other filters at specific time intervals during video processing. This guide explains how to format and configure these time intervals within a command list, enabling you to dynamically change filter parameters—such as text, volume, or video crop settings—at precise moments in your timeline.

Understanding sendcmd Syntax

The sendcmd filter reads commands either from a text file or directly from an inline string. Each line in the command list defines a time interval or a single timestamp, followed by the target filter, the command name, and the arguments.

The basic syntax for a command line is:

time_start [- time_end] command_target command_name command_arguments;

Specifying Time Intervals and Timestamps

You can define when a command executes using one of two methods: 1. Single Timestamp: Trigger a command once at a specific second. * Format: 10.5 (Triggers at exactly 10.5 seconds) * Format: 00:01:15 (Triggers at 1 minute and 15 seconds) 2. Time Interval (Range): Trigger commands upon entering or leaving a specific time window. * Format: 5.0-10.0 (Triggers when the timeline enters the 5 to 10-second range, and optionally when it leaves)

Step-by-Step Configuration Example

To demonstrate how to configure command intervals, we will use the drawtext filter to change displayed text over time.

Step 1: Create a Command File

Create a text file named commands.txt and define your intervals and commands. Ensure each line ends with a semicolon:

0.0-5.0 drawtext reinit 'text=Intro Scene';
5.0-10.0 drawtext reinit 'text=Main Scene';
10.0 drawtext reinit 'text=Ending Scene';

Step 2: Run the FFmpeg Command

Pass the command file to the sendcmd filter using the f (filename) parameter, and link it to the filter you want to control.

ffmpeg -i input.mp4 -filter_complex "sendcmd=f=commands.txt,drawtext=fontfile=font.ttf:text='':x=10:y=10" output.mp4

Using Inline Commands (Alternative)

If you do not want to use an external file, you can pass the interval configuration directly inline using the c parameter. Note that you must escape special characters and semicolons:

ffmpeg -i input.mp4 -filter_complex "sendcmd=c='5.0-10.0 drawtext reinit text=\'Active\';',drawtext=fontfile=font.ttf:text='Inactive':x=10:y=10" output.mp4

Interval Trigger Behavior

When you define a range like start-end (e.g., 5.0-10.0), FFmpeg executes the command based on state changes: * Enter: Executes when the video timeline reaches the start time (e.g., 5.0 seconds). * Leave: Executes when the video timeline exits the end time (e.g., 10.0 seconds).

This default behavior can be customized by prepending the command target with [enter] or [leave]. For example: * 5.0-10.0 [enter] volume volume 0.5; (Lowers volume only upon entering the interval) * 5.0-10.0 [leave] volume volume 1.0; (Restores volume only upon leaving the interval)