How to Format FFmpeg sendcmd Command Text Files

This article provides a comprehensive guide on how to format the command text file used by the FFmpeg sendcmd and asendcmd filters. You will learn the exact syntax rules, time interval formats, and command structures required to dynamically alter filter parameters during audio or video processing.

The Basic Syntax Structure

The sendcmd filter reads a text file containing instructions to change filter parameters at specific timestamps. Each active line in the command file must follow this structural template:

time_range target_filter command parameter_value;

time_range: Specifies when the command should trigger.
target_filter: The specific name or identifier of the filter you want to control (e.g., drawtext, volume).
command: The specific parameter of the target filter you want to modify (e.g., reinit, volume).
parameter_value: The new value you are assigning to that parameter.

Each command line must end with a semicolon ;. You can write comments in the file by starting the line with a # character. Empty lines are ignored.

Formatting Time Ranges

FFmpeg allows you to specify the trigger time in several formats. You can use single time instances or time intervals.

Single Time Instances

A single time instance triggers the command exactly when the playback reaches that timestamp. * Seconds: 5.0 (triggers at exactly 5 seconds) * Timecode: 00:01:15.500 (triggers at 1 minute, 15 seconds, and 500 milliseconds)

Time Intervals

An interval triggers the command when entering the interval, and can trigger a reset or different action when leaving the interval. * Format: start_time-end_time * Example: 2.0-5.0 (active between second 2 and second 5)

Writing Commands and Arguments

You can target a filter by its class name or by a specific instance name if you have assigned one using the id parameter in your filtergraph.

Example 1: Changing Volume (Audio)

To change the volume using asendcmd, your text file (e.g., commands.txt) would look like this:

# Reduce volume to 20% at 3 seconds
3.0 volume volume 0.2;

# Restore volume to 100% at 8 seconds
8.0 volume volume 1.0;

Example 2: Updating Text (Video)

To update the text displayed by a drawtext filter, you must first assign an id to the filter in your FFmpeg command, then reference that ID in your text file:

FFmpeg Command:

ffmpeg -i input.mp4 -vf "drawtext=id=my_text:text='Initial Text':x=100:y=100,sendcmd=f=commands.txt" output.mp4

commands.txt:

# Change the text at 2 seconds
2.0 my_text reinit text='First Update';

# Change the text again at 5 seconds
5.0 my_text reinit text='Second Update';

Multiple Commands at the Same Time

You can trigger multiple commands at the exact same timestamp. Separate individual commands with commas , under a single time definition:

# Change both text and color of the drawtext filter at 4 seconds
4.0 my_text reinit text='Alert!', drawtext reinit text_color=red;