How to Format FFmpeg sendcmd Command Files

The FFmpeg sendcmd (and audio equivalent asendcmd) filter allows you to dynamically send commands to other filters at specified timestamps during processing without re-encoding multiple times. This article explains the exact syntax and structure required to create a valid command text file for sendcmd, covers intervals and timestamps, and provides practical examples for controlling video and audio filters dynamically.

Basic Syntax Structure

A command file contains one or more directives, each terminating with a semicolon (;). You can write directives on single lines or across multiple lines. Lines beginning with # are treated as comments and ignored.

The standard syntax for a command entry is:

[START_TIME [, END_TIME]] TARGET COMMAND [ARGUMENTS];

START_TIME: The timestamp when the command is triggered. Can be expressed in seconds (e.g., 5, 12.350) or in hh:mm:ss[.xxx] format (e.g., 00:01:30.500).
END_TIME (Optional): The timestamp when the command terminates or reverts, applicable to filters supporting duration-based intervals.
TARGET: The name or label of the filter that should receive the command (e.g., drawtext, hue, volume).
COMMAND: The specific action supported by the target filter (e.g., reinit to re-initialize options).
ARGUMENTS: The parameter payload sent to the command (e.g., updated options like x=100:y=200).

Timestamp Formatting and Intervals

Timestamps dictate when the target filter receives the command. You can define single events or intervals:

Single Timestamp Event: Triggers a single command at the specified moment.
```
5.0 drawtext reinit text='Scene 2';
```
Interval with Start and End: Specifies an active window. Certain filters or command listeners process changes specifically within the boundaries of the interval.
```
00:00:10.000, 00:00:15.000 hue reinit h=180;
```

Escaping and Quoting Rules

Because FFmpeg uses spaces, colons, and semicolons as delimiters, arguments containing these characters must be enclosed in single or double quotes:

To pass multiple options to a reinit command, enclose the parameter string in single quotes:
```
2.5 drawtext reinit 'text=Breaking News:x=50:y=50';
```
If your text contains single quotes, escape them using standard FFmpeg escaping (\').

Complete Command File Examples

Example 1: Updating On-Screen Text Dynamically

File: text_events.txt

# Update the drawtext filter text at specified times
0.0 drawtext reinit 'text=Intro';
5.0 drawtext reinit 'text=Chapter 1';
15.0 drawtext reinit 'text=Chapter 2';
25.0 drawtext reinit 'text=Credits';

Corresponding FFmpeg command:

ffmpeg -i input.mp4 -vf "sendcmd=f=text_events.txt,drawtext=fontfile=font.ttf:text='':x=10:y=10:fontsize=24:fontcolor=white" output.mp4

Example 2: Adjusting Audio Volume Over Time

File: volume_events.txt

# Attenuate volume over specific timestamps
0.0 volume volume 1.0;
3.0 volume volume 0.2;
7.0 volume volume 1.0;

Corresponding FFmpeg command:

ffmpeg -i input.mp4 -af "asendcmd=f=volume_events.txt,volume=1.0" output.mp4

Example 3: Multiple Filters in a Single File

Multiple commands targeting different filters can be defined within the same file:

# Mute audio and change video brightness at second 10
10.0 volume volume 0.0;
10.0 eq reinit 'brightness=0.5';

# Restore values at second 15
15.0 volume volume 1.0;
15.0 eq reinit 'brightness=0.0';