Configure FFmpeg apulsator Frequency and Offset

The apulsator filter in FFmpeg is an audio effect used to create auto-pan and tremolo effects by modulating the volume of stereo channels. This article explains how to configure the frequency (hz) and phase offset (offsetl and offsetr) parameters of the apulsator filter to control the speed, direction, and width of the stereo panning effect.

Understanding the Key Parameters

To configure the auto-pan effect, you need to manipulate three primary parameters within the apulsator filter:

  1. hz (or frequency): This sets the modulation frequency in Hertz (Hz), which determines how fast the audio pans between the left and right channels. The default value is 2 Hz.
  2. offsetl (left offset): This sets the phase offset for the left channel. The value ranges from 0.0 to 1.0. The default is 0.0.
  3. offsetr (right offset): This sets the phase offset for the right channel. The value ranges from 0.0 to 1.0. The default is 0.5.

The relationship between offsetl and offsetr determines the stereo field movement. A difference of 0.5 means the channels are 180 degrees out of phase, creating a classic “ping-pong” panning effect where one channel goes quiet as the other reaches maximum volume.

Basic Syntax

The basic syntax for applying the apulsator filter in an FFmpeg command is:

ffmpeg -i input.mp3 -af "apulsator=hz=FREQUENCY:offsetl=LEFT_OFFSET:offsetr=RIGHT_OFFSET" output.mp3

Configuration Examples

1. Slow, Classic Auto-Pan (1 Hz)

To create a slow, soothing transition from left to right at a frequency of 1 Hz (one full cycle per second), use a phase difference of 0.5:

ffmpeg -i input.wav -af "apulsator=hz=1:offsetl=0:offsetr=0.5" output.wav

2. Fast, Tremolo-Like Pan (5 Hz)

For a rapid, pulsating effect, increase the frequency to 5 Hz while keeping the standard phase offsets:

ffmpeg -i input.wav -af "apulsator=hz=5:offsetl=0:offsetr=0.5" output.wav

3. In-Phase Tremolo (No Panning)

If you set both the left and right offsets to the same value, the volume of both channels will modulate simultaneously. This creates a standard tremolo effect rather than a panning effect:

ffmpeg -i input.wav -af "apulsator=hz=3:offsetl=0:offsetr=0" output.wav

4. Custom Stereo Width (Partial Phase Offset)

By setting the offset difference to something other than 0.5, you can create unique spatial patterns where the panning does not fully isolate to one side before moving to the other:

ffmpeg -i input.wav -af "apulsator=hz=2:offsetl=0.1:offsetr=0.3" output.wav

Additional Refinements

You can also combine these settings with the amount parameter (which controls the modulation depth, default is 1) and the mode parameter (which defines the waveform shape, such as sine, triangle, square, sawup, or sawdown). For example:

ffmpeg -i input.wav -af "apulsator=hz=2:offsetl=0:offsetr=0.5:amount=0.8:mode=triangle" output.wav

This command applies a triangle waveform at 2 Hz with an 80% modulation depth, resulting in a linear and smooth panning transition.