"""Impulse response synthesis from octave-band (or third-octave-band) energies.
The filter bank splits the spectrum into the eight octave bands with zero-phase,
half-octave raised-cosine crossovers, or into the 24 third-octave bands with crossovers
a sixth of an octave wide. The band gains sum to exactly one, so a signal split into
bands and summed again comes back unchanged (perfect reconstruction). Each function
takes the bands from the number of band signals or energies it is given (8 or 24).
Energy convention: the simulation gives time-integrated intensity for a source of unit
energy, so the direct sound at r metres carries 1 / (4 pi r^2). Impulse responses are
scaled by ``ENERGY_TO_IR`` so that this direct sound is an impulse of height 1 / r:
1 at 1 m, and 0.01 of energy at 10 m (the reference for strength G).
A path or time slot with energy ``E`` in every band becomes a broadband impulse or
noise burst of energy ``E``. Band energies are spectral levels, so the part of the
output inside band b carries ``E_b`` times that band's share of the spectrum.
"""
from __future__ import annotations
import functools
import math
import numpy as np
from acoustic_spaces import products
from acoustic_spaces.materials import bands as _bands
from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ
#: Impulse response energy per unit of simulated energy (time-integrated intensity).
ENERGY_TO_IR = 4.0 * math.pi
#: Energy of the impulse response of the direct sound at 10 m, the reference for G.
REFERENCE_ENERGY_10M = 0.01
#: Width of each crossover between octave bands, in octaves: half a band.
CROSSOVER_WIDTH = 0.5
#: Zero padding around FFT filtering, seconds; longer than the crossovers ring.
_PAD_S = 0.2
[docs]
def crossover_frequencies(bands: int = len(OCTAVE_BANDS_HZ)) -> np.ndarray:
"""Edges between adjacent bands (Hz) of the 8 octave bands or 24 third-octave bands."""
return _bands.crossover_frequencies(_bands.resolution_of(bands))
[docs]
def crossover_width(bands: int = len(OCTAVE_BANDS_HZ)) -> float:
"""Width of each crossover (octaves): half a band."""
return CROSSOVER_WIDTH / _bands.BANDS_PER_OCTAVE[_bands.resolution_of(bands)]
[docs]
def band_gains(n_fft: int, sample_rate: float, bands: int = len(OCTAVE_BANDS_HZ)) -> np.ndarray:
"""Zero-phase gains (bands, n_fft // 2 + 1) on the rFFT grid of the 8 octave bands
or 24 third-octave bands; they sum to one."""
return _band_gains(int(n_fft), float(sample_rate), int(bands)).copy()
@functools.lru_cache(maxsize=8)
def _band_gains(n_fft: int, sample_rate: float, bands: int = len(OCTAVE_BANDS_HZ)) -> np.ndarray:
f = np.fft.rfftfreq(n_fft, 1.0 / sample_rate)
log_f = np.log2(np.maximum(f, 1e-6))
width = crossover_width(bands)
steps = []
for edge in np.log2(crossover_frequencies(bands)):
x = np.clip((log_f - (edge - width / 2)) / width, 0.0, 1.0)
steps.append(np.sin(0.5 * np.pi * x) ** 2) # 0 below the edge, 1 above
steps = np.array(steps)
gains = np.empty((bands, len(f)))
gains[0] = 1.0 - steps[0]
gains[1:-1] = steps[:-1] - steps[1:]
gains[-1] = steps[-1]
gains.flags.writeable = False
return gains
[docs]
def fft_size(n: int, sample_rate: float) -> int:
"""FFT length for filtering n samples with zero padding on both sides."""
return 1 << int(math.ceil(math.log2(n + 2 * int(_PAD_S * sample_rate) + 1)))
[docs]
def combine_bands(
band_signals: np.ndarray, sample_rate: float, quadrature: np.ndarray | None = None
) -> np.ndarray:
"""Filter each band signal with its band and sum: (bands, n) -> (n,). With
``quadrature`` (bands, n), signals to add a quarter turn ahead in phase (their
spectra times j)."""
band_signals = np.asarray(band_signals, dtype=float)
n = band_signals.shape[1]
n_fft = fft_size(n, sample_rate)
spectrum = np.fft.rfft(band_signals, n_fft, axis=1)
if quadrature is not None:
spectrum = spectrum + 1j * np.fft.rfft(np.asarray(quadrature, dtype=float), n_fft, axis=1)
gains = _band_gains(n_fft, float(sample_rate), len(band_signals))
out = np.fft.irfft((spectrum * gains).sum(axis=0), n_fft)
return out[:n]
[docs]
def equalized(signal: np.ndarray, sample_rate: float, gains) -> np.ndarray:
"""``signal`` (n, ...) along its first axis through a zero-phase filter whose gain
in each band is ``gains`` (8 octave bands or 24 third-octave bands), going from one
to the next across the bands' crossovers (:func:`band_gains`); the same gain in
every band is that gain at every frequency."""
signal = np.asarray(signal, dtype=float)
n = len(signal)
n_fft = fft_size(n, sample_rate)
gains = np.asarray(gains, dtype=float)
curve = products.product(gains, _band_gains(n_fft, float(sample_rate), len(gains)))
spectrum = np.fft.rfft(signal, n_fft, axis=0)
curve = curve.reshape((-1,) + (1,) * (signal.ndim - 1))
return np.fft.irfft(spectrum * curve, n_fft, axis=0)[:n]
[docs]
def matched_gains(gains, sample_rate: float, rounds: int = 30) -> np.ndarray:
"""Gains for :func:`equalized` (8 octave bands or 24 third-octave bands) whose filter
changes the energy of white noise in each band, as :func:`split_bands` splits it,
by ``gains`` squared. Across a crossover :func:`equalized` goes from one band's gain
to the next's, so where they differ a band takes some of its neighbour's; these are
``gains`` nudged until each band's energy is its own, as near as ``rounds`` rounds
get it (to 0.001 dB): for gains stepping 12 dB from band to band, the lower ones
some 5 dB further down. A band of no gain stays at none."""
gains = np.asarray(gains, dtype=float)
shapes = _band_gains(1 << 16, float(sample_rate), len(gains))
weights = shapes**2
wanted = gains**2 * weights.sum(axis=1)
out = gains.copy()
for _ in range(rounds):
got = products.product(weights, products.product(out, shapes) ** 2)
ratio = np.divide(wanted, got, out=np.ones_like(got), where=got > 0.0)
out = out * np.sqrt(ratio)
if np.all(np.abs(10.0 * np.log10(ratio[wanted > 0.0])) < 1e-3):
break
return out
[docs]
def split_bands(
signal: np.ndarray, sample_rate: float, bands: int = len(OCTAVE_BANDS_HZ)
) -> np.ndarray:
"""Split a signal into the 8 octave bands or 24 third-octave bands: (n, ...) ->
(bands, n, ...), along its first axis; the bands sum to the input. As the bands are
zero-phase, what each spreads before the first sample or after the last is not in
it (see :func:`acoustic_spaces.parameters.octave_bands`)."""
signal = np.asarray(signal, dtype=float)
n = len(signal)
n_fft = fft_size(n, sample_rate)
spectrum = np.fft.rfft(signal, n_fft, axis=0)
gains = _band_gains(n_fft, float(sample_rate), int(bands))
gains = gains.reshape(gains.shape + (1,) * (signal.ndim - 1))
return np.fft.irfft(spectrum[None] * gains, n_fft, axis=1)[:, :n]
[docs]
def band_energy_share(
sample_rate: float, n_fft: int = 1 << 16, bands: int = len(OCTAVE_BANDS_HZ)
) -> np.ndarray:
"""Energy of a unit impulse inside each band: its share of the spectrum."""
g = band_gains(n_fft, sample_rate, bands) ** 2
weights = np.full(g.shape[1], 2.0)
weights[0] = 1.0
if n_fft % 2 == 0:
weights[-1] = 1.0
return (g * weights).sum(axis=1) / n_fft
[docs]
def place_impulses(
delays_s: np.ndarray,
amplitudes: np.ndarray,
length: int,
sample_rate: float,
taps: int = 32,
) -> np.ndarray:
"""Band signals (bands, length) with a fractional-delay impulse per path.
``amplitudes`` is (paths, bands). Delays between samples use a Hann-windowed sinc.
"""
amplitudes = np.atleast_2d(np.asarray(amplitudes, dtype=float))
out = np.zeros((amplitudes.shape[1], length))
if len(amplitudes) == 0:
return out
pos = np.asarray(delays_s, dtype=float) * sample_rate
base = np.floor(pos).astype(np.int64)
frac = pos - base
k = np.arange(-taps // 2 + 1, taps // 2 + 1)
x = k[None, :] - frac[:, None]
kernel = np.sinc(x) * np.where(np.abs(x) < taps / 2, np.cos(np.pi * x / taps) ** 2, 0.0)
idx = base[:, None] + k[None, :]
inside = (idx >= 0) & (idx < length)
for b in range(out.shape[0]):
values = amplitudes[:, b, None] * kernel
np.add.at(out[b], idx[inside], values[inside])
return out
[docs]
def placing_bytes(paths: int, taps: int = 32) -> int:
"""Bytes :func:`place_impulses` holds beside its output while it places ``paths``
impulses: six arrays (paths, taps) of eight bytes an element, one of one byte, and
three (paths,)."""
return paths * (8 * (6 * taps + 3) + taps)
def _slots(n: int, sample_rate: float, time_step: float) -> np.ndarray:
"""The time slot of ``time_step`` each of ``n`` samples falls in."""
return np.floor(np.arange(n) / (sample_rate * time_step) + 1e-9).astype(np.int64)
[docs]
def dirac_sequence(
length: int,
sample_rate: float,
volume_m3: float | None,
speed_of_sound: float,
rng: np.random.Generator,
time_step: float,
) -> np.ndarray:
"""Random-sign impulses whose density grows like reflections in a room: 4 pi c^3 t^2 / V.
Every time slot of :func:`shape_noise` (``time_step`` long, a whole number of samples
or not) gets at least one impulse, so no slot's energy is lost.
"""
t = np.arange(length) / sample_rate
if volume_m3 is None:
density = np.full(length, float(sample_rate))
else:
density = 4.0 * np.pi * speed_of_sound**3 * t**2 / volume_m3
density = np.clip(density, 1000.0, sample_rate)
pulses = rng.random(length) < density / sample_rate
signs = np.where(rng.random(length) < 0.5, -1.0, 1.0)
seq = np.where(pulses, signs, 0.0)
slot = _slots(length, sample_rate, time_step)
for s in np.flatnonzero(np.bincount(slot, weights=np.abs(seq)) == 0):
start, stop = np.searchsorted(slot, [s, s + 1])
seq[rng.integers(start, stop)] = signs[start]
return seq
[docs]
def smooth_energy(
energy: np.ndarray, time_step: float, start_s: float, window_s: float = 0.01
) -> np.ndarray:
"""Spread each slot's energy after ``start_s`` over a ``window_s`` window centred
on it.
The late energy of a ray tracer is a sum of discrete hits; a single strong ray late
in the tail would become a click. Smoothing moves energy by at most half a window
and keeps the total. A slot within half a window of ``start_s`` or of the end
spreads over the part of its window from ``start_s`` to the end, so no energy moves
ahead of ``start_s`` (into the early window of C50, when that is 50 ms after the
direct sound) or past the end.
"""
energy = np.asarray(energy, dtype=float)
n = energy.shape[-1]
half = int(round(window_s / time_step / 2.0))
start = int(math.ceil(start_s / time_step))
if half < 1 or start >= n:
return energy.copy()
out = energy.copy()
out[..., start:] = 0.0
# The slots whose whole window lies after start_s: a moving average.
first, last = start + half, n - half
if last > first:
width = 2 * half + 1
inner = np.zeros_like(energy)
inner[..., first:last] = energy[..., first:last]
padded = np.pad(inner, [(0, 0)] * (inner.ndim - 1) + [(half, half)])
cumulative = np.cumsum(padded, axis=-1)
cumulative = np.concatenate([np.zeros_like(cumulative[..., :1]), cumulative], axis=-1)
out += (cumulative[..., width:] - cumulative[..., :-width]) / width
# The others, near either end: over the part of their window inside.
for k in (*range(start, min(first, n)), *range(max(last, first), n)):
low, high = max(k - half, start), min(k + half, n - 1)
out[..., low : high + 1] += energy[..., k : k + 1] / (high - low + 1)
return out
[docs]
def shape_noise(
energy: np.ndarray,
time_step: float,
noise: np.ndarray,
sample_rate: float,
) -> np.ndarray:
"""Band signals (bands, n): ``noise`` scaled so each slot carries ``energy[band, slot]``."""
slot = np.minimum(_slots(len(noise), sample_rate, time_step), energy.shape[1] - 1)
noise_energy = np.bincount(slot, weights=noise**2, minlength=energy.shape[1])
with np.errstate(divide="ignore", invalid="ignore"):
gain = np.where(noise_energy > 0, np.sqrt(energy / noise_energy), 0.0)
return gain[:, slot] * noise[None, :]