How to Use the FFmpeg asendcmd Filter

The asendcmd (audio send command) filter in FFmpeg allows you to pass commands to other audio filters dynamically at specific time intervals during processing. This article provides a straightforward guide on how to configure and use the asendcmd filter, illustrating how to change audio parameters—such as volume or panning—on the fly using inline commands or external command files.

Understanding asendcmd Syntax

The asendcmd filter works by monitoring the audio stream's timeline. When a specified timestamp is reached, it dispatches a command to a designated target filter. To make this work, the target filter must be assigned a unique name (or identifier) using the @ syntax.

The basic syntax for a command is:

[time] [target_filter_identifier] [parameter_to_change] [new_value]
  • Time: The precise time (in seconds or HH:MM:SS format) when the command should trigger.
  • Target: The specific filter instance to receive the command (e.g., volume@my_volume).
  • Parameter: The parameter within that filter to adjust (e.g., volume).
  • Value: The new value to apply.

Method 1: Using Inline Commands

For simple, one-off changes, you can write the command directly inside the FFmpeg execution string using the c (command) argument.

Example: Dropping Volume at 5 Seconds

In this example, the audio starts at normal volume, but at exactly 5.0 seconds, the volume drops to 20% (0.2).

ffmpeg -i input.wav -af "asendcmd=c='5.0 volume@myvol volume 0.2',volume@myvol=1" output.wav

How it works:

  1. volume@myvol=1 initializes a volume filter with the instance name myvol and a default volume of 1 (100%).
  2. asendcmd=c='5.0 volume@myvol volume 0.2' instructs FFmpeg to target volume@myvol at the 5.0-second mark and change its volume parameter to 0.2.

Method 2: Using an External Command File

For complex audio manipulations with multiple triggers, managing commands inside a text file is highly recommended. You can load this file using the f (filename) argument.

Step 1: Create the Command File

Create a text file named commands.txt and define your sequence of events. Each command must end with a semicolon (;).

2.0 volume@myvol volume 0.5;
4.0 volume@myvol volume 0.1;
6.0 volume@myvol volume 1.0;

Step 2: Run FFmpeg with the Command File

Reference the commands.txt file in your FFmpeg command:

ffmpeg -i input.wav -af "asendcmd=f=commands.txt,volume@myvol=1" output.wav

How it works:

  • At 2.0 seconds, the volume scales down to 50%.
  • At 4.0 seconds, the volume drops to 10%.
  • At 6.0 seconds, the volume restores to 100%.

Key Considerations

  • Filter Compatibility: Not all FFmpeg audio filters support command injection. Common compatible filters include volume, pan, aecho, aphaser, and bandpass.
  • Naming Filters: You must explicitly label your target filter using the @ symbol (e.g., filter_name@my_unique_id) so asendcmd knows exactly where to direct the instruction.
  • Syntax Escaping: Depending on your operating system’s command line (Bash, PowerShell, or Windows CMD), you may need to adjust single and double quoting to prevent parser errors.