How to Change FFmpeg Filters at Runtime with sendcmd

FFmpeg provides the sendcmd (video) and asendcmd (audio) filters to dynamically alter filter parameters during processing without restarting or splicing streams. This guide covers how to structure runtime commands, format external command files, use inline directives, and apply real-time modifications to both video and audio pipelines through practical, copy-pasteable examples.

Understanding sendcmd and asendcmd

The sendcmd and asendcmd filters monitor the playback timeline and dispatch configuration commands downstream to other filters. For a target filter to respond, it must support dynamic command processing (e.g., hue, drawbox, volume, eq).

Commands can be delivered in two ways:

  1. File mode (f): Reads commands from an external text file.
  2. Command mode (c): Directly executes commands defined inline within the FFmpeg command string.

Command Syntax Structure

Every command executed by sendcmd follows this syntax:

[START_TIME[-END_TIME]] [FLAGS] TARGET_FILTER COMMAND [ARGUMENTS];
  • START_TIME[-END_TIME]: The timestamp in seconds (e.g., 5.0 or 5.0-10.0) when the command takes effect.
  • FLAGS: Optional execution flags, such as [enter] (triggers when entering the interval) or [leave] (triggers when exiting the interval).
  • TARGET_FILTER: The name or explicit instance name of the target filter.
  • COMMAND: The action to trigger, typically reinit to re-initialize parameters.
  • ARGUMENTS: The updated filter parameters to apply.

Modifying Video Filters with sendcmd

Method 1: Using an External Command File

Using a file is recommended for managing complex or multiple timeline changes.

  1. Create a text file named video_cmds.txt:
2.0 hue reinit h=90;
5.0 hue reinit h=180:s=2;
8.0 hue reinit h=0:s=1;
  1. Run the FFmpeg command referencing the file:
ffmpeg -i input.mp4 -vf "sendcmd=f=video_cmds.txt,hue=h=0:s=1" -c:a copy output.mp4

In this pipeline, the video begins with default saturation and zero hue rotation. At second 2, the hue rotates by 90 degrees; at second 5, the hue changes to 180 degrees with doubled saturation; at second 8, the baseline settings are restored.

Method 2: Using Inline Commands

For simple, single-event modifications, define the command directly using the c parameter:

ffmpeg -i input.mp4 -vf "sendcmd=c='3.0-6.0 [enter] drawbox reinit color=red@0.5 [leave] drawbox reinit color=blue@0.5',drawbox=x=10:y=10:w=100:h=100:color=green" -c:a copy output.mp4

Between seconds 3 and 6, the box color switches to red. When leaving the interval at second 6, the box turns blue.

Modifying Audio Filters with asendcmd

The asendcmd filter functions identically to sendcmd, but operates on audio streams.

Example: Dynamic Volume Adjustments

  1. Create a text file named audio_cmds.txt:
3.0 volume reinit volume=0.2;
7.0 volume reinit volume=1.0;
  1. Run FFmpeg:
ffmpeg -i input.mp4 -af "asendcmd=f=audio_cmds.txt,volume=1.0" -c:v copy output.mp4

At second 3, the volume attenuates to 20% of its normal level. At second 7, it returns to full volume.

Targeting Specific Filter Instances

When using multiple instances of the same filter in a pipeline, assign a custom label using @ syntax to ensure commands affect only the intended filter:

ffmpeg -i input.mp4 -vf "sendcmd=c='2.0 drawbox@alert reinit color=red',drawbox@static=x=0:y=0:w=50:h=50:color=white,drawbox@alert=x=100:y=100:w=200:h=200:color=black" output.mp4

The runtime update only applies to drawbox@alert, leaving drawbox@static unchanged.