How to Duck Audio in FFmpeg Using Sidechaincompress

Audio ducking automatically lowers the volume of background music whenever a voiceover speaks, ensuring speech remains intelligible without manually adjusting volume keyframes. In FFmpeg, this is achieved using the sidechaincompress audio filter within a filter_complex graph. This article explains how the filter works, provides a ready-to-use command, and breaks down the essential parameters required to tune the compression for a clean, professional mix.

The Basic Ducking Command

To duck background music behind a voiceover and combine them into a single audio file, use the following command:

ffmpeg -i music.mp3 -i voice.wav -filter_complex \
"[0:a][1:a]sidechaincompress=threshold=0.1:ratio=5:attack=20:release=300[ducked]; \
 [ducked][1:a]amix=inputs=2:dropout_transition=2[outa]" \
-map "[outa]" output.mp3

How the Filter Graph Works

  1. Routing Inputs ([0:a][1:a]sidechaincompress): The sidechaincompress filter requires two audio inputs. The first input ([0:a], your background music) is the target signal that gets compressed. The second input ([1:a], your voiceover) is the sidechain trigger that controls the compression level.
  2. Generating the Ducked Track ([ducked]): Whenever the voiceover volume crosses the specified threshold, FFmpeg attenuates the music signal and outputs it to a temporary label called [ducked].
  3. Mixing the Signals (amix): The ducked music ([ducked]) and the original voiceover ([1:a]) are merged into a final, unified stereo stream mapped to [outa].

Key Parameters Explained

You can fine-tune the behavior of sidechaincompress using these core options:

  • threshold (e.g., 0.1): Sets the detection volume level (between 0.000976563 and 1.0) at which compression begins. Lower values make the filter more sensitive to quieter speech, while higher values require louder speech to trigger attenuation.
  • ratio (e.g., 5): Determines the intensity of the volume reduction applied to the music. A ratio of 4 or 5 provides natural, subtle ducking, whereas values like 10 or higher will aggressively lower the music level.
  • attack (e.g., 20): The amount of time, in milliseconds, it takes for the music volume to decrease once the voice starts. A short attack (10–30 ms) prevents the first syllables of speech from competing with loud music.
  • release (e.g., 300): The duration, in milliseconds, it takes for the music to return to its original volume after the voice stops speaking. Setting this between 250 and 500 ms prevents the audio from "pumping" or abruptly jumping in volume during brief pauses between words.
  • makeup (e.g., 1): Adjusts the overall gain applied to the compressed signal. Leaving this at default (1) maintains the original track level during silence.

Ducking Audio in a Video File

If you want to duck background music against a video containing an integrated voice track and replace the audio stream entirely:

ffmpeg -i video.mp4 -i music.mp3 -filter_complex \
"[1:a][0:a]sidechaincompress=threshold=0.1:ratio=5:attack=20:release=300[ducked]; \
 [ducked][0:a]amix=inputs=2:dropout_transition=2[outa]" \
-map 0:v -map "[outa]" -c:v copy -c:a aac output.mp4

In this variation, the video's audio ([0:a]) acts as the voiceover trigger, the external music file ([1:a]) is ducked, and -c:v copy ensures the video stream is preserved without re-encoding.