How to Use Sidechain Compression in FFmpeg

Sidechain compression is a powerful audio processing technique where the volume level of one audio signal dynamically controls the volume level of another, commonly used to "duck" background music under a voiceover. This article provides a straightforward guide on how to use the sidechaincompress filter in FFmpeg, covering its essential parameters and practical command-line examples to help you achieve professional audio ducking in your projects.

Understanding the sidechaincompress Filter

The sidechaincompress filter in FFmpeg accepts two audio inputs:

  1. The main input (Input 0): The audio stream that will be compressed (e.g., background music).
  2. The sidechain input (Input 1): The trigger audio stream that controls the compression (e.g., a voiceover).

When the sidechain input exceeds a specified threshold, the volume of the main input is automatically reduced.

Key Parameters

You can customize the compression behavior using the following parameters:

  • threshold: The level above which the sidechain signal triggers compression. Value range is from 0.0009765635 to 1.0 (default is 0.125). Lower values make the compressor more sensitive.
  • ratio: The amount of gain reduction applied once the signal crosses the threshold. For example, a ratio of 4 (4:1) significantly reduces the music volume, while 2 (2:1) is more subtle.
  • attack: The time in milliseconds it takes for the volume to drop once the sidechain signal starts (default is 20ms).
  • release: The time in milliseconds it takes for the volume to return to normal after the sidechain signal stops (default is 250ms).
  • makeup: The output gain boost applied to the compressed signal (default is 1.0).

Practical Command Examples

Example 1: Basic Audio Ducking

In this scenario, we have a background music file (music.mp3) and a voiceover file (voice.wav). We want to compress the music whenever the voiceover is active, and then mix them together into a final output file.

ffmpeg -i music.mp3 -i voice.wav -filter_complex "[0:a][1:a]sidechaincompress=threshold=0.1:ratio=4:attack=15:release=300[ducked];[ducked][1:a]amix=inputs=2:duration=first[aout]" -map "[aout]" output.mp3

How this command works:

  1. -i music.mp3 -i voice.wav: Imports the music as input 0 ([0:a]) and the voiceover as input 1 ([1:a]).
  2. [0:a][1:a]sidechaincompress: Uses the voiceover to compress the music.
    • threshold=0.1 ensures the compressor activates quickly when speaking begins.
    • ratio=4 reduces the music volume significantly during speech.
    • attack=15 and release=300 ensure smooth transitions.
    • The result is labeled as [ducked].
  3. [ducked][1:a]amix=inputs=2: Mixes the ducked music track back together with the original voiceover so both can be heard in the output.
  4. -map "[aout]": Maps the final mixed audio stream to the output file output.mp3.

Example 2: Ducking Music Inside a Video File

If you have a video file that already contains background music, and a separate voiceover file, you can apply the filter and output a new video file without re-encoding the video stream.

ffmpeg -i video_with_music.mp4 -i voiceover.wav -filter_complex "[0:a][1:a]sidechaincompress=threshold=0.15:ratio=5[ducked];[ducked][1:a]amix=inputs=2[aout]" -map 0:v -c:v copy -map "[aout]" -c:a aac output.mp4

How this command works:

  • -map 0:v -c:v copy: Copies the video stream directly from the input video to the output without re-encoding, preserving video quality and saving processing time.
  • The audio streams are processed using the same sidechain and mixing logic, then encoded to AAC format using -c:a aac.