all thanks to Cursor AI for coding this object.
help file: hrtf 3d.axh (6.8 KB)
object: hrtf 3d.axo (9.7 KB)
# HRTF 3D Spatial Audio Processor
A real-time 3D spatial audio processor for Axoloti/Ksoloti that provides binaural stereo output for immersive headphone listening experiences.
## Features
- **Full 360° Azimuth Control**: Complete horizontal positioning from front to back
- **Elevation Control**: Vertical positioning with volume attenuation at extremes
- **Distance Attenuation**: Realistic distance-based volume and air absorption
- **Binaural Output**: Optimized for headphone listening
- **Low DSP Usage**: Efficient implementation for real-time performance
## Inlets
### Audio Input
- **Type**: `frac32buffer`
- **Description**: Mono audio input to be spatialized
- **Usage**: Connect any audio source (oscillator, sample, etc.)
### Azimuth Control
- **Type**: `frac32`
- **Range**: 0 to +64 (maps to 0° to 360°)
- **Description**: Horizontal angle control for full-circle positioning
- **Behavior**:
-
**0**: Front center (both ears)
-
**16**: Right side
-
**32**: Back center (both ears)
-
**48**: Left side
-
**64**: Front center (both ears, completes circle)
### Elevation Control
- **Type**: `frac32`
- **Range**: -64 to +64 (maps to -90° to +90°)
- **Description**: Vertical angle control with volume attenuation
- **Behavior**:
-
**-64**: Quieter volume (0.5x)
-
**0**: Normal volume (1.0x)
-
**+64**: Quieter volume (0.5x)
### Distance Control
- **Type**: `frac32`
- **Range**: 0 to +64 (maps to 0.1 to 10.0 units)
- **Description**: Distance from listener with realistic attenuation
- **Behavior**:
-
**0**: Very close (loud)
-
**32**: Medium distance
-
**64**: Far away (quiet with air absorption)
## Outlets
### Left Ear Output
- **Type**: `frac32buffer`
- **Description**: Left channel binaural output
- **Usage**: Connect to left headphone channel or mixer
### Right Ear Output
- **Type**: `frac32buffer`
- **Description**: Right channel binaural output
- **Usage**: Connect to right headphone channel or mixer
## Technical Details
### Azimuth Algorithm
- Uses direct angle-based panning for smooth transitions
- Maps 0-360° to stereo positioning with four quadrants
- Provides front/back distinction for immersive spatialization
### Elevation Algorithm
- Simple volume-based elevation effect
- Maintains normal volume at horizontal (0°)
- Reduces volume at vertical extremes (±90°)
### Distance Algorithm
- Inverse square law attenuation
- Frequency-dependent air absorption simulation
- Minimum 10% volume at maximum distance
### Performance
- Optimized for real-time processing
- Low DSP usage compared to convolution-based HRTF
- Suitable for live performance and real-time applications
## Usage Examples
### Basic Spatial Audio
```
Audio Source → HRTF 3D → Headphones
↑
Control Signals
```
### Automated Movement
```
LFO → Math/Scale → Azimuth Inlet
LFO → Math/Scale → Elevation Inlet
LFO → Math/Scale → Distance Inlet
```
### Interactive Control
```
Dial → Azimuth Inlet (manual positioning)
Dial → Elevation Inlet (manual height)
Dial → Distance Inlet (manual distance)
```
## Tips for Best Results
1. **Use Headphones**: Designed specifically for binaural headphone listening
2. **Start with Azimuth**: The azimuth control provides the most noticeable spatial effect
3. **Subtle Elevation**: Elevation changes are more subtle - use for fine-tuning
4. **Distance for Depth**: Use distance control to create depth and atmosphere
5. **Combine Controls**: Use all three controls together for full 3D positioning
## Limitations
- Simplified HRTF implementation (not full convolution-based)
- Optimized for performance over accuracy
- Best results with headphones (not speakers)
- Limited to mono input (stereo input will be summed)
## Version History
- **v1.0**: Initial release with azimuth, elevation, and distance controls
- Optimized for Ksoloti/Axoloti platform
- Full 360° azimuth mapping with front/back distinction
## License
GPL v3.0 - See LICENSE file for details.
## Author
Ksoloti Community
