PipeWire 7.1 Virtual Surround Sound

This repository contains a custom PipeWire daemon configuration (pipewire.conf) that enables 7.1 virtual surround sound for standard stereo headphones.

It utilizes PipeWire's libpipewire-module-filter-chain along with a convolution filter to process an 8-channel audio stream using a HeSuVi Head-Related Impulse Response (HRIR) file, downmixing it into a highly immersive spatial stereo output.

🚀 Features

• 7.1 Channel Downmixing: Intercepts 7.1 surround sound input from games and media.
• HRIR Convolution: Uses HeSuVi 14-channel WAV files (such as atmos.wav) for accurate 3D spatial positioning.
• Low Latency Native Audio: Runs directly within the PipeWire graph with realtime priority scheduling.

📋 Prerequisites

Before installing, ensure your Linux environment meets the following requirements:

• PipeWire (This config is based on version 1.4.7)
• WirePlumber or a compatible PipeWire session manager
• A HeSuVi 14-channel HRIR file: You will need a compatible .wav file (e.g., an Atmos HRIR from the HeSuVi project).

🛠️ Installation

1. Prepare the HRIR File

You need a HeSuVi 14-channel .wav impulse response file.

1. Obtain your preferred HRIR file and rename it to atmos.wav.
2. Create the local PipeWire config directory if it doesn't already exist:

   mkdir -p ~/.config/pipewire/
   

3. Place atmos.wav inside the ~/.config/pipewire/ directory.

2. Configure the File Paths (Important)

By default, the provided pipewire.conf file contains a hardcoded path to a specific user's home directory (/home/[YOUR_USER]/). You must edit the pipewire.conf file to match your actual username so PipeWire can find the HRIR file.

Open pipewire.conf, locate the filter.graph nodes section, and replace /home/[YOUR_USER]/ with the proper path for all 16 lines:

{ type = builtin label = convolver name = convFL_L config = { filename = "/home/YOUR_USERNAME/.config/pipewire/atmos.wav" channel =  0 } }
{ type = builtin label = convolver name = convFL_R config = { filename = "/home/YOUR_USERNAME/.config/pipewire/atmos.wav" channel =  1 } }
# ... update all remaining lines ...

3. Apply the Configuration

1. Copy your modified pipewire.conf into your local user PipeWire configuration directory:

   cp pipewire.conf ~/.config/pipewire/pipewire.conf
   

   (Note: Placing it in ~/.config/pipewire/ limits the changes to your user. For system-wide changes, use /etc/pipewire/pipewire.conf instead).

2. Restart your PipeWire audio services to apply the new configuration:

   systemctl --user restart pipewire pipewire-pulse wireplumber
   

🎮 Usage

Once the services have restarted successfully, open your desktop environment's sound settings (e.g., KDE/GNOME audio settings) or pavucontrol.

1. Look for a new Output Device named "7.1 Virtual Surround Sink".
2. Set it as your Default Output Device.
3. Any game or media player will now output 7.1 surround to this sink, which will convolve the audio using your HRIR file and output spatialized stereo to your physical headphones.

💡 Troubleshooting

• No Sound / Sink Missing? Double-check the absolute paths to the atmos.wav file in pipewire.conf. If PipeWire cannot locate the convolution .wav file at the exact path specified, the filter chain module will fail to load, and the sink will not appear.
• Routing Issues: You can use a patchbay tool like qpwgraph or Helvum to visually inspect your PipeWire routing. Ensure the 7.1 Virtual Surround Sink is capturing the audio and that its mixL and mixR outputs are correctly wired to the playback ports of your physical stereo headphones.