How to Use the FFmpeg sidechaincompress Filter

This article provides a straightforward guide on how to use the sidechaincompress filter in FFmpeg to implement sidechain compression, a popular audio ducking technique. You will learn the basic syntax, key parameters like threshold and ratio, and see practical command-line examples to automatically lower the volume of a background music track whenever a voiceover plays.

Understanding Sidechain Compression in FFmpeg

Sidechain compression (often called “ducking”) uses the volume level of one audio signal (the control or trigger signal) to dynamically reduce the volume of another audio signal (the target signal). A common use case is lowering background music when a narrator speaks.

The sidechaincompress filter in FFmpeg requires two audio inputs: 1. First input (Input 0): The audio stream that you want to compress (e.g., background music). 2. Second input (Input 1): The trigger audio stream that controls the compression (e.g., a voiceover).

Key Parameters

You can customize the compression behavior using the following parameters:

• threshold: The volume level (from 0.000963 to 1.0) of the trigger signal that initiates compression. Lower values make the compressor trigger more easily. Default is 0.125.
• ratio: The compression ratio (from 1 to 20). It determines how much the target audio is quieted. A ratio of 10:1 or higher creates a distinct “ducking” effect. Default is 2.
• attack: The time in milliseconds (from 0.01 to 2000) it takes for the compressor to reduce the volume once the trigger exceeds the threshold. Default is 20.
• release: The time in milliseconds (from 0.01 to 9000) it takes for the target audio to return to its original volume after the trigger drops below the threshold. Default is 250.
• makeup: The output gain boost in decibels (dB) applied to the compressed signal. Default is 0.

Practical Command Example

Here is a standard FFmpeg command that ducks background music (music.mp3) using a voiceover track (voice.mp3):

ffmpeg -i music.mp3 -i voice.mp3 -filter_complex "[0:a][1:a]sidechaincompress=threshold=0.05:ratio=12:attack=10:release=500[outa]" -map "[outa]" output.mp3

How the filter graph works:

• -i music.mp3: Input 0 (target audio to be compressed).
• -i voice.mp3: Input 1 (trigger audio).
• [0:a][1:a]: Feeds the audio from both inputs into the filter.
• threshold=0.05: Triggers compression at a low voice volume.
• ratio=12: Significantly reduces the music volume.
• attack=10: Quickly ducks the music (10 milliseconds) as soon as speaking begins.
• release=500: Smoothly fades the music back in over half a second (500 milliseconds) during pauses.
• [outa]: Names the output audio stream.
• -map "[outa]": Tells FFmpeg to write the processed audio to the output file.

Mixing the Audios Together

In most scenarios, you want to hear both the ducked music and the voiceover in the final output. To do this, use the amix filter after applying sidechaincompress:

ffmpeg -i music.mp3 -i voice.mp3 -filter_complex "[0:a][1:a]sidechaincompress=threshold=0.05:ratio=12:attack=10:release=500[compressed_music];[compressed_music][1:a]amix=inputs=2:duration=first[outa]" -map "[outa]" output.mp3

In this command, the compressed music stream ([compressed_music]) is mixed with the original voiceover stream ([1:a]) to create a cohesive final master file.