How to Configure FFmpeg Sidechain Compressor Settings

This guide explains how to configure the key parameters—threshold, ratio, attack, and release—of the sidechain compressor filter (sidechaincompress) in FFmpeg. You will learn the exact syntax, parameter ranges, and practical command-line examples to duck audio dynamically, ensuring professional-sounding mixes where one audio track automatically lowers the volume of another.

The Sidechain Compressor Filter Syntax

In FFmpeg, the sidechaincompress filter requires two audio inputs. The first input is the main audio stream (the signal to be compressed/ducked), and the second input is the sidechain signal (the trigger, such as a voiceover).

The basic syntax for the filter is:

[main_audio][sidechain_audio]sidechaincompress=parameter1=value1:parameter2=value2[output_audio]

Parameter Configurations

To control how the compression behaves, you must configure the following four essential parameters:

1. Threshold (threshold)

The threshold determines the volume level of the sidechain signal required to trigger the compression on the main signal.

  • Values: A linear amplitude scale ranging from 0.000976563 to 1.0 (default is 0.125).
  • Configuration: A lower value (e.g., 0.05) makes the compressor highly sensitive, triggering volume reduction even with quiet sidechain signals. A higher value (e.g., 0.3) requires a much louder sidechain signal to initiate ducking.

2. Ratio (ratio)

The ratio determines the amount of gain reduction applied to the main audio once the sidechain signal crosses the threshold.

  • Values: A float value between 1.0 and 20.0 (default is 2.0).
  • Configuration: For gentle background ducking, a ratio between 2.0 and 4.0 is ideal. For heavy ducking (where the background music needs to drop significantly), use a higher ratio such as 10.0 or 20.0.

3. Attack (attack)

The attack parameter controls how quickly (in milliseconds) the compressor reduces the volume of the main audio once the sidechain signal exceeds the threshold.

  • Values: A float value in milliseconds from 0.01 to 2000.0 (default is 20.0).
  • Configuration: For voiceovers, a fast attack time of 10.0 to 20.0 ms is recommended so the music ducks instantly when the speaker begins talking.

4. Release (release)

The release parameter controls how quickly (in milliseconds) the main audio returns to its original volume after the sidechain signal drops back below the threshold.

  • Values: A float value in milliseconds from 0.01 to 9000.0 (default is 250.0).
  • Configuration: A release time that is too short causes unnatural volume "pumping," while a release time that is too long keeps the music quiet for too long after the speaking stops. A smooth release time for voice ducking is typically between 200.0 and 400.0 ms.

Practical FFmpeg Command Example

The following command ducks a background music track (music.mp3) using a voiceover track (voice.mp3) as the sidechain trigger:

ffmpeg -i music.mp3 -i voice.mp3 -filter_complex "[0:a][1:a]sidechaincompress=threshold=0.07:ratio=5:attack=15:release=300[outa]" -map "[outa]" output.mp3

Explanation of the Command:

  • -i music.mp3: Input 0 (the main audio to be ducked).
  • -i voice.mp3: Input 1 (the sidechain trigger).
  • [0:a][1:a]: Feeds the audio from the first input and second input into the filter.
  • threshold=0.07: Sets a highly sensitive threshold to catch quiet speech.
  • ratio=5: Sets a 5:1 compression ratio for distinct ducking.
  • attack=15: Fast 15ms reaction time to lower the music immediately when speaking starts.
  • release=300: Smooth 300ms fade-back time for the music once speaking ends.
  • -map "[outa]": Maps the processed output to the final file output.mp3.