HRTF Setup

This guide explains how to set up HRTF (Head-Related Transfer Function) spatialization in your Amplitude project for immersive 3D binaural audio. HRTF uses measured or simulated impulse responses from human ears to reproduce spatial audio over standard stereo headphones.

Prerequisites¶

Before you begin, ensure you have:

• Amplitude Audio SDK v1.0 or later
• An .amir HRIR sphere file (see Generating an AMIR file)
• Headphones for testing (HRTF is optimized for headphone playback)

What is HRTF?¶

HRTF captures how sound waves interact with the human head, torso, and pinnae (outer ears) as they travel from a sound source to each ear. By convolving audio with these direction-specific impulse responses, Amplitude can create a convincing 3D audio experience using only two audio channels.

Amplitude supports multiple HRIR datasets:

Step 1: Generate or Obtain an AMIR File¶

Amplitude uses its own optimized .amir format for HRIR data. You can generate one from supported datasets using the amir CLI tool:

# Convert a SOFA file to AMIR (model 3 = SOFA)
amir -m 3 input.sofa output.amir

# Convert IRCAM data to AMIR (model 0 = IRCAM)
amir -m 0 /path/to/ircam/ output.amir

# Resample to a target sample rate during conversion (model 1 = MIT)
amir -m 1 -r 48000 /path/to/mit_kemar/ output.amir

The amir tool will:

1. Read the HRIR dataset
2. Compute interaural time differences (ITD)
3. Triangulate the sphere mesh
4. Output an optimized .amir file for runtime use

Step 2: Configure the Engine¶

Add the HRTF section to your engine configuration file:

{
  "driver": "miniaudio",
  "output": {
    "frequency": 48000,
    "buffer_size": 4096,
    "format": "Float32"
  },
  "mixer": {
    "panning_mode": "BinauralHighQuality",
    "active_channels": 50,
    "virtual_channels": 100,
    "pipeline": "default.ampipeline"
  },
  "hrtf": {
    "amir_file": "data/sadie_h12.amir",
    "hrir_sampling": "Bilinear"
  }
}

Configuration Options¶

Panning Modes¶

Choose a binaural panning mode in the mixer configuration:

Step 3: Configure Sound Objects for HRTF¶

Ensure your sound objects use HRTF spatialization:

{
  "id": 10,
  "name": "footsteps",
  "path": "sounds/footsteps.wav",
  "spatialization": "HRTF",
  "attenuation": 1
}

Available spatialization modes:

Step 4: Set Up Listeners and Entities¶

HRTF spatialization depends on accurate listener and entity positions. Ensure your game updates these each frame:

// Update listener position and orientation
listener.SetLocation(playerPosition);
listener.SetOrientation(playerOrientation);

// Update entity (sound source) position
entity.SetLocation(enemyPosition);
entity.SetOrientation(enemyOrientation);

// Optional: set directivity for more realistic radiation patterns
entity.SetDirectivity(0.5f, 2.0f);

Step 5: Verify the Pipeline¶

The default pipeline includes HRTF processing through the AmbisonicBinauralDecoder node. If you are using a custom pipeline, ensure it includes the necessary nodes:

{
  "id": 1,
  "name": "hrtf_pipeline",
  "nodes": [
    { "id": 1, "name": "Input", "consume": [] },
    { "id": 2, "name": "Attenuation", "consume": [1] },
    { "id": 3, "name": "AmbisonicPanning", "consume": [2] },
    { "id": 4, "name": "AmbisonicRotator", "consume": [3] },
    { "id": 5, "name": "AmbisonicBinauralDecoder", "consume": [4] },
    { "id": 6, "name": "Output", "consume": [5] }
  ]
}

Runtime API¶

You can query and configure HRTF settings at runtime:

// Get the current HRIR sphere (returns std::shared_ptr<const HRIRSphere>)
auto sphere = amEngine->GetHRIRSphere();

// Check if the sphere is loaded
if (sphere != nullptr && sphere->IsLoaded())
{
    amLogInfo("HRIR sphere loaded with %u vertices", sphere->GetVertexCount());
}

// Query the current sampling mode
eHRIRSphereSamplingMode mode = amEngine->GetHRIRSphereSamplingMode();

Performance Considerations¶

Troubleshooting¶

Next Steps¶

• Learn about ambisonic spatialization for speaker-based VR setups.
• Explore the HRIRSphere API Reference.
• Learn how to build custom HRIR datasets with the amir CLI tool.