Head-related impulse responses (audiotoolbox.HRIRSet)

The HRIRSet class holds a set of head-related impulse responses (HRIRs) measured over a number of spatial directions. The impulse responses are stored as a regular audiotoolbox.Signal of shape (n_taps, n_directions, 2) while the source directions are kept in a separate position table. It provides direction lookup, interpolation, and binaural rendering, and can load measurements from SOFA files.

class audiotoolbox.HRIRSet(hrirs: Signal, positions, coordinate_system: str = 'spherical', units: str | None = None)

A set of head-related impulse responses measured over directions.

The impulse responses are stored time-domain in a audiotoolbox.Signal of shape (n_taps, 2, n_directions) where the first channel axis holds the (left, right) ear. The associated source directions are kept in a separate position table.

Parameters:

hrirs (Signal) – Time-domain impulse responses of shape (n_taps, 2, n_directions).
positions (array_like) – Source directions of shape (n_directions, 2) or (n_directions, 3) given as (azimuth, elevation[, distance]). Angles are in degrees.
coordinate_system (str, optional) – Name of the coordinate system the positions are given in (default = "spherical").
units (str, optional) – Free-form description of the position units (e.g. the SOFA SourcePosition_Units string). Stored for reference only.

Examples

>>> import numpy as np, audiotoolbox as audio
>>> hrirs = audio.Signal((2, 4), 128 / 48000, 48000)  # L/R x 4 directions
>>> positions = np.array([[0, 0], [90, 0], [180, 0], [270, 0]])
>>> hrir_set = audio.HRIRSet(hrirs, positions)
>>> hrir_set.n_directions
4

property azimuth: ndarray: Azimuth of every measured direction in degrees.

property distance: ndarray | None: Measurement distance per direction, or None if not stored.

property elevation: ndarray: Elevation of every measured direction in degrees.

classmethod from_sofa(filename: str) → HRIRSet

Load an HRIR set from a SOFA file.

Reads a SOFA file (the standard interchange format for HRTFs) using the sofar library. The convention is expected to store the impulse responses in Data_IR with shape (n_directions, 2, n_taps) (e.g. SimpleFreeFieldHRIR).

Parameters:

filename (str) – Path to the .sofa file.

Returns:

The loaded HRIR set.

Return type:

HRIRSet

Raises:

ImportError – If the optional sofar dependency is not installed.
ValueError – If the file does not provide two-receiver impulse responses.

property fs: int: Sampling rate in Hz.

interpolate(azimuth: float, elevation: float) → HRIRSet

Return an interpolated HRIR for an arbitrary direction.

For a fully three-dimensional measurement grid the impulse responses of the three directions forming the surrounding spherical triangle are combined using barycentric weights. For a planar grid (e.g. a horizontal ring) the two angularly adjacent directions are interpolated instead. If the requested direction lies outside the measured region, the nearest measured HRIR is returned.

Note that this performs a straight linear combination of the impulse responses; for widely spaced measurements time-alignment before interpolation would reduce comb-filtering artefacts.

Parameters:

azimuth (float) – Query azimuth in degrees.
elevation (float) – Query elevation in degrees.

Returns:

Single-direction HRIRSet containing the interpolated HRIR.

Return type:

HRIRSet

property n_directions: int: Number of measured directions.

property n_taps: int: Length of each impulse response in samples.

nearest(azimuth, elevation) → HRIRSet

Return the HRIR of the closest measured direction.

Parameters:

azimuth (float or array_like) – Query azimuth(s) in degrees.
elevation (float or array_like) – Query elevation(s) in degrees.

Returns:

Subset of one (scalar query) or many (vectorized query) nearest measured directions.

Return type:

HRIRSet

render(signal, azimuth: float | None = None, elevation: float | None = None, interpolate: bool = True, mode: Literal['full', 'same', 'valid'] = 'full') → Signal

Spatialize a signal with one or many HRIR directions.

If azimuth/elevation are provided, a single direction is selected (nearest or interpolated) and rendered as binaural output.

If no direction is provided, this HRIRSet is used directly: - mono input (n, 1) is rendered against all stored directions - multichannel input (n, K) must match K == n_directions and

is rendered channel-wise against matching HRIR directions.

Batched set rendering returns output with channel shape (2, K) i.e. array shape (n_out, 2, K).

Parameters:

signal (Signal or ndarray) – The mono source signal. If an ndarray is passed it is wrapped using the HRIR set’s sampling rate.
azimuth (float, optional) – Source azimuth in degrees.
elevation (float, optional) – Source elevation in degrees.
interpolate (bool, optional) – If True (default) the HRIR is barycentrically interpolated, otherwise the nearest measured HRIR is used.
mode ({'full', 'same', 'valid'}, optional) – Convolution mode passed to audiotoolbox.Signal.convolve() (default = 'full').

Returns:

Binaural output. Single-direction rendering returns shape (n_out, 2); batched set rendering returns (n_out, 2, K).

Return type:

Signal

summary() → str: Short human-readable description of the HRIR set.

to_hrtf()

Return the frequency-domain transfer functions.

Converts the stored impulse responses to the frequency domain. As with audiotoolbox.Signal.to_freqdomain() this is not done in place; a new audiotoolbox.FrequencyDomainSignal of shape (n_taps, 2, n_directions) is returned.

Returns:: The head-related transfer functions.
Return type:: FrequencyDomainSignal