Load Custom HRIR WAV Files in FFmpeg

This guide explains how to load and use custom Head-Related Impulse Response (HRIR) WAV files with the FFmpeg headphone filter to create spatial, binaural 3D audio. You will learn the exact command-line syntax required to map multi-channel audio sources to your custom HRIR files and how to resolve common sample rate mismatches.

Step 1: Prepare Your Files

To virtualize multi-channel audio (such as 5.1 or 7.1 surround sound) into a binaural headphone mix, you need: 1. The Source Audio: A multi-channel audio or video file. 2. The HRIR WAV File: A multi-channel WAV file containing the impulse responses for each virtual speaker position.

Note: The sample rate of your HRIR WAV file must exactly match the sample rate of your source audio (typically 44100 Hz or 48000 Hz). If they do not match, you must resample them.

Step 2: The FFmpeg Command Syntax

The headphone filter in FFmpeg uses a complex filtergraph (-filter_complex). It takes the multi-channel audio as the first input, the HRIR WAV file as the second input, and maps them together.

Here is the template command for a 5.1 surround sound input (6 channels) using a single multi-channel HRIR file:

ffmpeg -i input.mp4 -i hrir.wav -filter_complex "[0:a][1:a]headphone=map=FL|FR|FC|LFE|BL|BR[out]" -map "[out]" -map 0:v -c:v copy output.mp4

Parameter Breakdown

• -i input.mp4: Input index 0 (the source video/audio).
• -i hrir.wav: Input index 1 (the custom HRIR file).
• [0:a][1:a]: Feeds the audio from the first input and the audio from the second input into the filter.
• headphone=map=...: Activates the headphone filter. The map argument specifies the order of virtual speakers as they appear in your HRIR WAV file.
  • FL (Front Left)
  • FR (Front Right)
  • FC (Front Center)
  • LFE (Low-Frequency Effects / Subwoofer)
  • BL (Back Left)
  • BR (Back Right)
• [out]: The labeled output of the filter, which is mapped to the final file via -map "[out]".
• -c:v copy: Copies the video stream without re-encoding to save time.

Handling Sample Rate Mismatches

If your input file and HRIR file have different sample rates, FFmpeg will throw an error. You can fix this by adding a resampling filter (aresample) to the filtergraph before passing the streams to the headphone filter:

ffmpeg -i input.mp4 -i hrir.wav -filter_complex "[0:a]aresample=48000[main];[1:a]aresample=48000[hrir];[main][hrir]headphone=map=FL|FR|FC|LFE|BL|BR[out]" -map "[out]" -map 0:v -c:v copy output.mp4

In this command, both the source audio and the HRIR audio are resampled to 48,000 Hz on the fly before being processed by the spatializer.