237 lines
7.0 KiB
Markdown
237 lines
7.0 KiB
Markdown
# Valhallir Convoluter
|
|
|
|
A CLI tool for processing WAV files to generate impulse responses (IR) from sweep and recorded WAV files, designed for guitar speaker IR creation.
|
|
|
|
## Features
|
|
|
|
- **Fast FFT-based deconvolution** for accurate IR extraction
|
|
- **Automatic input conversion:** Accepts any WAV sample rate, bit depth, or channel count
|
|
- **Optional output IR length:** Specify output IR length in milliseconds with --length-ms
|
|
- **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
|
|
- **Automatic silence trimming** and normalization
|
|
- **Modular design** with separate packages for WAV I/O and convolution
|
|
- **Robust error handling** and validation
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd valhallir-convoluter
|
|
|
|
# Build the application
|
|
go build -o valhallir-convoluter
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic IR Generation
|
|
|
|
Generate a standard impulse response from sweep and recorded files (any WAV format):
|
|
|
|
```sh
|
|
./valhallir-convoluter --sweep sweep.wav --recorded recorded.wav --output ir.wav
|
|
```
|
|
|
|
### With Minimum Phase Transform
|
|
|
|
Generate both regular and minimum phase IRs:
|
|
|
|
```sh
|
|
./valhallir-convoluter --sweep sweep.wav --recorded recorded.wav --output ir.wav --mpt
|
|
```
|
|
|
|
This creates:
|
|
- `ir.wav` - Standard impulse response
|
|
- `ir_mpt.wav` - Minimum phase transform version
|
|
|
|
### Limit Output IR Length
|
|
|
|
Trim or zero-pad the output IR to a specific length (in milliseconds):
|
|
|
|
```sh
|
|
./valhallir-convoluter --sweep sweep.wav --recorded recorded.wav --output ir.wav --length-ms 100
|
|
```
|
|
|
|
This will ensure the output IR is exactly 100 ms long (trimming or zero-padding as needed).
|
|
|
|
### Different Output Formats
|
|
|
|
Generate IRs in different sample rates and bit depths:
|
|
|
|
```sh
|
|
# 44kHz 16-bit (CD quality)
|
|
./valhallir-convoluter \
|
|
--sweep sweep.wav \
|
|
--recorded recorded.wav \
|
|
--output ir_cd.wav \
|
|
--sample-rate 44100 \
|
|
--bit-depth 16
|
|
|
|
# 48kHz 32-bit (studio quality)
|
|
./valhallir-convoluter \
|
|
--sweep sweep.wav \
|
|
--recorded recorded.wav \
|
|
--output ir_studio.wav \
|
|
--sample-rate 48000 \
|
|
--bit-depth 32 \
|
|
--mpt
|
|
|
|
# 96kHz 24-bit (high resolution)
|
|
./valhallir-convoluter \
|
|
--sweep sweep.wav \
|
|
--recorded recorded.wav \
|
|
--output ir_hires.wav \
|
|
--sample-rate 96000 \
|
|
--bit-depth 24
|
|
```
|
|
|
|
### Advanced Options
|
|
|
|
```sh
|
|
./valhallir-convoluter \
|
|
--sweep sweep.wav \
|
|
--recorded recorded.wav \
|
|
--output ir.wav \
|
|
--mpt \
|
|
--sample-rate 48000 \
|
|
--bit-depth 24 \
|
|
--normalize 0.95 \
|
|
--trim-threshold 0.001 \
|
|
--length-ms 50
|
|
```
|
|
|
|
## Command Line Options
|
|
|
|
| Flag | Description | Default | Required |
|
|
|------|-------------|---------|----------|
|
|
| `--sweep` | Path to sweep WAV file (any format) | - | Yes |
|
|
| `--recorded` | Path to recorded WAV file (any format) | - | Yes |
|
|
| `--output` | Path to output IR WAV file | - | Yes |
|
|
| `--mpt` | Generate minimum phase transform IR | false | No |
|
|
| `--sample-rate` | Output sample rate (44, 48, 88, 96 kHz) | 96000 | No |
|
|
| `--bit-depth` | Output bit depth (16, 24, 32 bit) | 24 | No |
|
|
| `--normalize` | Normalize output to peak value (0.0-1.0) | 0.95 | No |
|
|
| `--trim-threshold` | Silence threshold for trimming (0.0-1.0) | 0.001 | No |
|
|
| `--length-ms` | Output IR length in milliseconds (trim or zero-pad) | - | No |
|
|
|
|
## File Requirements
|
|
|
|
### Input Files
|
|
- **Format:** Any uncompressed WAV file
|
|
- **Sample Rate:** Any (will be automatically resampled to 96kHz for processing)
|
|
- **Bit Depth:** Any (16, 24, 32-bit supported; will be converted to float64 internally)
|
|
- **Channels:** Any (mono, stereo, or multi-channel; will be converted to mono by averaging channels)
|
|
|
|
### Output Files
|
|
- **Format:** WAV files
|
|
- **Sample Rate:** 44kHz, 48kHz, 88kHz, or 96kHz (set by `--sample-rate`)
|
|
- **Bit Depth:** 16-bit, 24-bit, or 32-bit (set by `--bit-depth`)
|
|
- **Channels:** Mono (1 channel)
|
|
|
|
## Technical Details
|
|
|
|
### Input Conversion
|
|
- All input files are automatically converted to mono, 96kHz, float64 for processing
|
|
- Stereo or multi-channel files are averaged to mono
|
|
- Sample rates are resampled to 96kHz using linear interpolation
|
|
- Bit depths are normalized to float64
|
|
|
|
### Output IR Length
|
|
- If `--length-ms` is set, the output IR (and MPT IR) will be trimmed or zero-padded to the specified length in milliseconds
|
|
- If not set, the full IR is used
|
|
|
|
### Deconvolution Process
|
|
1. **FFT-based deconvolution** of recorded signal by sweep signal
|
|
2. **Regularization** to prevent division by zero
|
|
3. **Silence trimming** to remove leading/trailing silence
|
|
4. **Normalization** to prevent clipping
|
|
|
|
### Minimum Phase Transform
|
|
- Uses **real cepstrum method** for accurate minimum phase conversion
|
|
- **Reduces latency** by minimizing pre-ringing
|
|
- **Maintains frequency response** while optimizing phase characteristics
|
|
- **Suitable for real-time applications** like guitar amp modeling
|
|
|
|
### 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)
|
|
- **File Sizes:** 16-bit ≈ 50% smaller, 32-bit ≈ 33% larger than 24-bit
|
|
|
|
## Dependencies
|
|
|
|
- [urfave/cli](https://github.com/urfave/cli) - CLI framework
|
|
- [go-audio/wav](https://github.com/go-audio/wav) - WAV file I/O
|
|
- [go-dsp/fft](https://github.com/mjibson/go-dsp) - FFT implementation
|
|
- [gonum](https://gonum.org/) - Numerical computing
|
|
|
|
## Examples
|
|
|
|
### Guitar Cabinet IR (CD Quality)
|
|
```sh
|
|
# Generate IR from guitar cab sweep and recording (any WAV format), 50ms length
|
|
./valhallir-convoluter \
|
|
--sweep guitar_cab_sweep.wav \
|
|
--recorded guitar_cab_recorded.wav \
|
|
--output cab_ir_cd.wav \
|
|
--sample-rate 44100 \
|
|
--bit-depth 16 \
|
|
--length-ms 50 \
|
|
--mpt
|
|
```
|
|
|
|
### Room Acoustics IR (Studio Quality)
|
|
```sh
|
|
# Generate room impulse response
|
|
./valhallir-convoluter \
|
|
--sweep room_sweep.wav \
|
|
--recorded room_recorded.wav \
|
|
--output room_ir_studio.wav \
|
|
--sample-rate 48000 \
|
|
--bit-depth 24
|
|
```
|
|
|
|
### High-Resolution IR (Mastering)
|
|
```sh
|
|
# Generate high-resolution IR for mastering
|
|
./valhallir-convoluter \
|
|
--sweep mastering_sweep.wav \
|
|
--recorded mastering_recorded.wav \
|
|
--output mastering_ir.wav \
|
|
--sample-rate 96000 \
|
|
--bit-depth 32 \
|
|
--length-ms 100 \
|
|
--mpt
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**"File is not a valid WAV file" error**
|
|
- Check that files are uncompressed WAV format
|
|
- Avoid MP3, FLAC, or other compressed formats
|
|
|
|
**"Invalid sample rate" error (output)**
|
|
- Use only supported output sample rates: 44100, 48000, 88200, 96000
|
|
- Check the `--sample-rate` flag value
|
|
|
|
**"Invalid bit depth" error (output)**
|
|
- Use only supported output bit depths: 16, 24, 32
|
|
- Check the `--bit-depth` flag value
|
|
|
|
### Performance
|
|
- Processing time depends on file length
|
|
- FFT-based deconvolution is much faster than time-domain methods
|
|
- Large files (>1GB) may take several minutes
|
|
- Higher bit depths require more memory but don't significantly affect processing time
|
|
|
|
## License
|
|
|
|
[Add your license information here]
|
|
|
|
## Contributing
|
|
|
|
[Add contribution guidelines here] |