From da00906732d0701bd8ad463558e21d84d2520d03 Mon Sep 17 00:00:00 2001
From: menekis <_a+B*9y[%Q8)>
Date: Sun, 19 Jul 2026 15:21:28 -0400
Subject: [PATCH] adding initial Readme

---
 README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7f229e2..bdb2ec7 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,61 @@
-# pipewire-virtual-surround
+# 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:
+   ```bash
+   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:
+```conf
+{ 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:
+   ```bash
+   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:
+   ```bash
+   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.