Source code for acoustic_spaces.spatial.decoder

"""Binaural decoding: filters that turn the AmbiX channels of a sound field into the
signals at the two ears (:func:`binaural_decoder`), or the channels of a loudspeaker
layout, each speaker heard as a virtual one (:func:`binaural_filters` gives the filters
of either format).

The Ambisonics filters fit the HRTF of every measured direction with the spherical
harmonics up to the order (least squares, ``"ls"``). Low orders cannot follow the fast
changes of the HRTF's phase with direction at high frequencies, and least squares then
loses level and spaciousness; above a cutoff (the order times 600 Hz, after Schörkhuber,
Zaunschirm and Höldrich 2018) the magnitude least squares decoder (``"magls"``, the
default) fits only the magnitudes and keeps the phase that varies smoothly from the bin
below.
"""

from __future__ import annotations

import math
from typing import TYPE_CHECKING

import numpy as np

from acoustic_spaces import products
from acoustic_spaces.spatial.ambisonics import MAX_ORDER, Ambisonics, real_spherical_harmonics
from acoustic_spaces.spatial.hrtf import HRTF
from acoustic_spaces.spatial.loudspeakers import Loudspeakers

if TYPE_CHECKING:
    from acoustic_spaces.spatial.render import Format

#: Decoding methods.
DECODERS = ("magls", "ls")
#: Above this many hertz per order, ``magls`` fits magnitudes only.
MAGLS_HZ_PER_ORDER = 600.0


[docs] def binaural_decoder(order: int, hrtf: HRTF, method: str = "magls") -> np.ndarray: """Filters (taps, (order + 1) ** 2, 2) from the AmbiX channels of ``order`` to the left and right ear, at the HRTF's sample rate. A plane wave encoded from a direction decodes to about that direction's HRTF.""" if not 0 <= order <= MAX_ORDER: raise ValueError(f"Ambisonics order must be 0 to {MAX_ORDER}, got {order}") if method not in DECODERS: raise ValueError(f"unknown decoder {method!r}; choose from {', '.join(DECODERS)}") harmonics = real_spherical_harmonics(order, hrtf.directions) # (directions, channels) inverse = np.linalg.pinv(harmonics) # Fit on a fine frequency grid, then keep a filter twice the HRIRs' length. fine = _power_of_two(max(8 * hrtf.taps, 2048)) taps = _power_of_two(max(2 * hrtf.taps, 64)) spectra = np.fft.rfft(hrtf.hrir, fine, axis=-1).transpose(2, 0, 1) # (bins, dirs, 2) filters = products.product(inverse, spectra) # (bins, channels, 2) if method == "magls": frequencies = np.fft.rfftfreq(fine, 1.0 / hrtf.sample_rate) start = int(np.searchsorted(frequencies, MAGLS_HZ_PER_ORDER * max(order, 1))) # Each bin takes the phase of the fit one bin below, advanced by the delay # common to all the HRIRs, so the filters keep the HRIRs' timing. delay = float(np.median(np.argmax(np.abs(hrtf.hrir), axis=-1))) advance = np.exp(-2j * math.pi * delay / fine) magnitudes = np.abs(spectra) for k in range(max(start, 1), len(frequencies)): phase = np.exp(1j * np.angle(products.product(harmonics, filters[k - 1]))) * advance filters[k] = products.product(inverse, magnitudes[k] * phase) out = np.fft.irfft(filters, fine, axis=0)[:taps] # (taps, channels, 2) fade = taps // 8 out[taps - fade :] *= (0.5 + 0.5 * np.cos(np.linspace(0.0, math.pi, fade)))[:, None, None] return np.ascontiguousarray(out)
[docs] def binaural_filters(fmt: Format, hrtf: HRTF, method: str = "magls") -> np.ndarray: """Filters (taps, channels, 2) from the channels of ``fmt`` to the left and right ear, at the HRTF's sample rate, so that a signal in ``fmt`` is heard as it plays: for :class:`~acoustic_spaces.spatial.Ambisonics`, :func:`binaural_decoder` of its order; for :class:`~acoustic_spaces.spatial.Loudspeakers`, each speaker as a virtual one, the HRTF of its direction (:meth:`HRTF.interpolate`), and the LFE channel, which the renders leave silent, as nothing.""" if isinstance(fmt, Ambisonics): return binaural_decoder(fmt.order, hrtf, method) if isinstance(fmt, Loudspeakers): out = np.zeros((hrtf.taps, fmt.channels, 2)) mains = [k for k, speaker in enumerate(fmt.speakers) if not speaker.lfe] out[:, mains] = hrtf.interpolate(fmt.directions()[mains]).transpose(2, 0, 1) return out raise ValueError( f"{fmt.label}: only Ambisonics and loudspeaker layouts are decoded to the two ears" )
def _power_of_two(n: int) -> int: return 1 << int(math.ceil(math.log2(n))) __all__ = ["DECODERS", "MAGLS_HZ_PER_ORDER", "binaural_decoder", "binaural_filters"]