Load Custom HRIR in FFmpeg Headphone Filter

This article provides a direct guide on using custom Head-Related Impulse Response (HRIR) WAV files with FFmpeg's headphone audio filter to produce binaural spatial audio. You will learn the correct command-line structure for both single multi-channel HRIR files and multiple separate impulse response files, how to map channels accurately, and how to handle sample rate matching.

Preparing Your Inputs

To process audio through the headphone filter, you need:

  1. A multi-channel audio source (such as 5.1 or 7.1 surround sound).
  2. One or more custom HRIR WAV files that contain the stereo impulse response measurements corresponding to each speaker position.

The sample rates of your input audio and the HRIR files must match exactly. If they differ, you must resample the audio streams within the filtergraph using the aresample filter.

Method 1: Using a Single Multi-Channel HRIR WAV File

If your custom HRIR is bundled into a single multichannel WAV file containing interleaved stereo pairs for each channel, pass the main audio as the first input and the HRIR file as the second input.

ffmpeg -i surround_input.wav -i custom_hrir.wav -filter_complex "[0:a][1:a]headphone=map=FL|FR|FC|LFE|BL|BR[out]" -map "[out]" output_binaural.wav

In this command:

  • [0:a] specifies the source multi-channel audio.
  • [1:a] specifies the custom HRIR WAV file.
  • map=FL|FR|FC|LFE|BL|BR defines the speaker positions in the order they appear inside the multi-channel HRIR file. Each named position corresponds to a stereo pair of impulse responses (e.g., channels 1 and 2 represent Front Left, 3 and 4 represent Front Right, and so on).

Method 2: Using Separate Stereo HRIR Files per Channel

If your custom HRIRs are stored as individual stereo WAV files for each physical speaker position, load each file as a distinct input and map them in sequence:

ffmpeg -i surround_input.wav \
  -i hrir_fl.wav \
  -i hrir_fr.wav \
  -i hrir_fc.wav \
  -i hrir_lfe.wav \
  -i hrir_bl.wav \
  -i hrir_br.wav \
  -filter_complex "[0:a][1:a][2:a][3:a][4:a][5:a][6:a]headphone=map=FL|FR|FC|LFE|BL|BR[out]" \
  -map "[out]" output_binaural.wav

Each additional input [1:a] through [6:a] is mapped sequentially to the positions declared in the map string.

Handling Sample Rates and Gain Adjustments

If your input files have mismatched sample rates or if spatialization causes digital clipping, use aresample and volume adjustments directly inside the filter chain:

ffmpeg -i surround_input.wav -i custom_hrir.wav -filter_complex \
  "[0:a]aresample=48000[src]; \
   [1:a]aresample=48000[hrir]; \
   [src][hrir]headphone=map=FL|FR|FC|LFE|BL|BR:gain=0[out]" \
  -map "[out]" output_binaural.wav

The gain parameter allows fine-tuning the output attenuation in decibels to prevent peaks from exceeding 0 dBFS.