IrateGoose - Virtual Surround Sound for PipeWire

IrateGoose is a graphical application that configures PipeWire to create a virtual sound card providing spatial audio directionality in headphones. It transforms standard 7.1 surround sound into binaural audio using Head-Related Transfer Function (HRTF) technology, giving you immersive 3D audio perception through regular stereo headphones.

How It Works
Installation
Configuration
Integration with EasyEffects
Finding the Right IR File
Troubleshooting
Removing Configuration
Technical Details
For Packaging
Building from Source
License
Acknowledgments
Support and Feedback

How It Works

IrateGoose creates a virtual PipeWire sink that processes 7.1 channel audio through a convolver using HRTF impulse response (IR) files. Here's what these terms mean:

HRTF (Head-Related Transfer Function)

HRTF is a mathematical model that describes how sound reaches your ears from different directions in space. It accounts for the shape of your head, ears, and torso, which affect how you perceive sound direction. By applying HRTF processing to surround sound, you can experience convincing 3D audio through headphones.

Convolver

A convolver is a digital signal processing component that applies an impulse response to an audio signal. In this context, it takes the 7.1 channel audio and "convolves" it with HRTF data to create binaural output that mimics how sound would arrive at your ears from different directions.

Impulse Response (IR) File

An impulse response file (typically a WAV file) contains the acoustic "fingerprint" of how a sound system (or in this case, a human hearing system) responds to an impulse. IR files contain measurements of how sound from each direction reaches both ears. IrateGoose uses multi-channel WAV files where each channel corresponds to a different speaker position.

Compatibility with HeSuVi

IrateGoose uses the same mathematical processing and the same IR file format as the popular HeSuVi (Headphone Surround Virtualization) software. If you're familiar with HeSuVi, you'll find that IrateGoose produces similar audio quality and uses the same IR files. This means you can use your existing HeSuVi IR collection with IrateGoose.

Installation

Prerequisites

Linux with PipeWire audio system (most modern Linux distributions use PipeWire by default)
5.1/7.1 channel audio source (games, media players, etc.)
Stereo headphones (any quality will work, but better headphones provide better results)

Step 1: Download IrateGoose

Download the latest binary from the Releases page

Step 2: Obtain IR Files

IrateGoose requires impulse response files in WAV format compatible with HeSuVi. You have several options:

Download from collection: Get IR files from the website: https://airtable.com/appayGNkn3nSuXkaz/shruimhjdSakUPg2m/tbloLjoZKWJDnLtTc
Extract from HeSuVi: If you already have HeSuVi installed, you can use the IR files from its HeSuVi/Common/ directory. These are typically located at: C:\Program Files\EqualizerAPO\config\HeSuVi\Common\. You can copy the WAV files from there to use with IrateGoose.
Use your own: Any multi-channel WAV file in HeSuVi format (14 channels for 7.1 processing) will work.

Step 3: Installation Options

IrateGoose offers two installation approaches:

Option A: Try Out the Application

If you want to try IrateGoose without installing it permanently:

Download the binary to any location
Start the application
On the Options tab, select the folder containing your WAV files

Option B: Install for Regular Use

For permanent installation:

Move the binary to a directory on your PATH (recommended: ~/.local/bin/)
Run the installation command to create a system menu entry:
```
irate_goose --install
```
This creates a .desktop file in the appropriate location for your desktop environment.
To uninstall (removes only the menu entry):
```
irate_goose --uninstall
```
Note: The binary and WAV files need to be removed manually if desired.

Application icon:

Command Line Options

IrateGoose supports several command-line options:

Set WAV folder temporarily: Specify the WAV folder path as an argument:
```
irate_goose /path/to/your/wav/files
```
This sets the WAV folder for this run only.

Install/uninstall menu entry:

irate_goose --install    # Create system menu entry
irate_goose --uninstall  # Remove system menu entry

Help: Display help information:
```
irate_goose --help
```

Configuration

Select an IR File

Launch IrateGoose. The application will display a list of detected WAV files with their descriptions:

Browse through the available IR files
Use the search box to find specific files
Filter by sample rate (48000 Hz, 44100 Hz, 96000 Hz, or all)
Select the IR file you want to use by clicking on it

The application can recognize some well-known IR files (by file name only) and show additional data:

HRTF name (e.g., SADIE, MIT, etc.)
Description of the measurement subject or method
Source and credits for the data

Configure Options

Before applying configuration, you can customize settings on the Options tab:

Virtual Device Name: Choose a custom name for your virtual sound card
WAV Folder: Set the directory containing your WAV files
Output Device: Select which audio sink the virtual surround should output to (default: Auto - let PipeWire decide)

About Output Device Selection

The Output Device option allows you to specify where the virtual surround sound should be routed:

Auto (default): Let PipeWire automatically choose the output device. This is usually your default audio output.
Specific audio sink: Select a particular output device (like "Built-in Audio", "HDMI", or "USB Headphones") to force the virtual surround to always output to that device.

This is useful when you have multiple audio outputs and want to ensure the virtual surround always plays through a specific device (e.g., always use your headphones even if they're not the default output).

Apply Configuration

Click the "Create Device" button to apply your selection. IrateGoose will:

Create a PipeWire configuration file at ~/.config/pipewire/pipewire.conf.d/sink-virtual-surround-7.1-irategoose.conf
Restart PipeWire services to apply the changes
Create a virtual sound card with your chosen name (default: "Virtual Surround Sink")
Configure the output routing based on your Output Device selection

Important: You can now close IrateGoose - it doesn't need to keep running! The configuration persists until you change or delete it.

Select the Virtual Sound Card

Open your desktop environment's sound settings (KDE System Settings, pavucontrol, etc.)
Look for "Virtual Surround Sink" in the output devices list
Select it as your playback device

Note for KDE Plasma users: Some desktop environments, like KDE Plasma, may not show virtual sound cards by default. You may need to enable "Show virtual devices" in the sound settings.

Configure Your Audio Sources

For spatial audio to work correctly, your applications must output 7.1 channel audio, not stereo or headphone audio:

Games:

Look for audio settings labeled "7.1 Surround", "Studio Speakers", "Reference Speakers", or "Home Theater"
Avoid settings labeled "Headphones", "Stereo", or "2.0"
Common settings:
- Windows Sonic or Dolby Atmos for Headphones: Disable these if using IrateGoose
- Speaker Configuration: Set to "7.1 Surround" or "7.1 Speakers"
- Audio Output: Set to "Speakers" not "Headphones"

In fact, failing to configure the game, and using two surround emulations at the same time, unlocks a secret Knight Mode™: an authentic feeling of a steel bucket on your head.

Media Players:

Configure to output multi-channel audio (not downmixed to stereo). Avoid upmixing stereo to 7.1 too as it may produce excessive echo. Stereo content should remain stereo, and you will hear it as if you are listening to 2.1 speakers.

System-Wide:

Ensure your system audio settings are configured for 7.1 output when using the virtual sink

Integration with EasyEffects

IrateGoose can be combined with EasyEffects (a system-wide audio effects processor) to apply additional audio processing like equalization, compression, or reverb after the virtual surround conversion.

Configuration Steps

Configure EasyEffects:
- Launch EasyEffects and ensure it has created its virtual device
- Go to Preferences → Audio and disable the checkbox "Process all output streams"
  - Explanation: By default, EasyEffects aggressively grabs audio from all applications. Disabling this option allows IrateGoose to process the audio first, then pass it to EasyEffects for further processing.
- In PipeWire → General, set a fixed output device where you want the final sound to play (e.g., your headphones)
**Co

IrateGoose

Install / Use

README