Add automatic phase correction with cross-correlation detection and manual override

- Implement cross-correlation-based phase inversion detection
- Add --force-invert-phase flag for manual override and testing
- Add --no-phase-correction flag to disable automatic detection
- Update README with comprehensive documentation
- Improve phase detection sensitivity and add detailed logging
- Ensure consistent IR polarity for easier mixing of multiple IRs

README.md

@@ -10,6 +10,8 @@ A CLI tool for processing WAV files to generate impulse responses (IR) from swee
 - **Optional low-cut and high-cut filtering:** Apply Butterworth filters to the recorded sweep before IR extraction (--lowcut, --highcut, --cut-slope)
 - **Automatic fade-out:** Linear fade-out at the end of the IR to avoid clicks (default 5 ms, configurable with --fade-ms)
 - **IR Visualization:** Generate frequency response and waveform plots with `--plot-ir`
+- **Automatic Phase Correction:** Detects and corrects phase-inverted recorded sweeps for consistent IR polarity
+- **Manual Phase Inversion:** Use `--force-invert-phase` to explicitly invert the recorded sweep for testing or manual override
 - **96kHz 24-bit WAV file support** for high-quality audio processing
 - **Multiple output formats** with configurable sample rates and bit depths
 - **Minimum Phase Transform (MPT)** option for reduced latency IRs
@@ -88,6 +90,31 @@ You can control the filter steepness (slope) with `--cut-slope` (in dB/octave, d
 
 This applies a 40 Hz low-cut and 18 kHz high-cut, both with a 24 dB/octave slope (steeper than the default 12).
 
+### Automatic Phase Correction
+
+Valhallir Deconvolver automatically detects and corrects phase-inverted recorded sweeps to ensure consistent IR polarity. This is especially important when mixing multiple IRs later.
+
+By default, the tool:
+- **Detects phase inversion** by analyzing the correlation between sweep and recorded signals
+- **Automatically corrects** phase-inverted recorded sweeps
+- **Ensures consistent polarity** across all generated IRs
+
+If you know your recorded sweep has the correct phase, you can disable automatic correction:
+
+```sh
+./valhallir-deconvolver --sweep sweep.wav --recorded recorded.wav --output ir.wav --no-phase-correction
+```
+
+### Forcing Phase Inversion (Testing/Manual Override)
+
+You can force the recorded sweep to be inverted (regardless of automatic detection) using:
+
+```sh
+./valhallir-deconvolver --sweep sweep.wav --recorded recorded.wav --output ir.wav --force-invert-phase
+```
+
+This is useful for testing or if you know your recorded sweep is out of phase and want to override the automatic detection.
+
 ### IR Visualization
 
 Generate frequency response and waveform plots of your IRs:
@@ -170,6 +197,8 @@ Generate IRs in different sample rates and bit depths:
 | `--highcut` | High-cut filter (low-pass) cutoff frequency in Hz (recorded sweep) | - | No |
 | `--cut-slope` | Filter slope in dB/octave (12, 24, 36, ...; default 12) | 12 | No |
 | `--plot-ir` | Generate frequency response and waveform plot | false | No |
+| `--no-phase-correction` | Disable automatic phase correction | false | No |
+| `--force-invert-phase` | Force inversion of the recorded sweep (manual override) | false | No |
 
 ## File Requirements
 
@@ -225,6 +254,12 @@ Generate IRs in different sample rates and bit depths:
 - **Automatic File Naming:** Plots are saved with the same base name as the IR file
 - **High-Quality Output:** PNG format suitable for documentation and sharing
 
+### Phase Correction
+- **Automatic Detection:** Analyzes correlation between sweep and recorded signals to detect phase inversion
+- **Smart Correction:** Uses the first 100ms of signals for reliable phase analysis
+- **Consistent Polarity:** Ensures all IRs have the same phase polarity for easy mixing
+- **Optional Disable:** Use `--no-phase-correction` if you know the phase is correct
+
 ### Output Format Options
 - **Sample Rates:** 44.1kHz (CD), 48kHz (studio), 88.2kHz, 96kHz (high-res)
 - **Bit Depths:** 16-bit (CD), 24-bit (studio), 32-bit (high-res)