"""Measuring impulse responses with exponential sine sweeps.
The usual chain is: generate an excitation (:class:`Sweep`), play it through a
loudspeaker while recording one or more microphones, deconvolve the recording into an
impulse response, then analyse it with :mod:`acoustic_spaces.parameters`, the same
code that analyses simulated responses.
- :class:`Sweep` is a synchronized exponential sweep (Novak et al., 2015): its
harmonic distortion lands in separate impulse responses *before* the linear one,
so deconvolution leaves the linear response clean. The excitation repeats the sweep
with silence after each one, long enough for the room to decay.
- :func:`deconvolve` divides spectra with Kirkeby regularisation outside the swept band,
then averages the repeats, which lowers background noise by 3 dB per doubling.
- :func:`measure` plays and records through ``sounddevice`` (the ``measure``
extra) and returns the deconvolved responses. A loopback
channel (an output wired straight back to an input) removes the latency of the
audio interface.
Rules of thumb: make the silence after each sweep longer than the reverberation time,
and the sweep itself about ten times longer than the reverberation time if distortion
products must not overlap the linear response at all.
"""
from __future__ import annotations
import json
import math
from collections.abc import Callable, Sequence
from dataclasses import asdict, dataclass
from pathlib import Path
import numpy as np
from acoustic_spaces._extras import install_hint
#: Regularisation inside and outside the swept band, relative to the peak power.
_EPS_IN, _EPS_OUT = 1e-8, 1.0
def _ramp(n: int) -> np.ndarray:
"""A raised-cosine fade-in of ``n`` samples."""
return np.sin(0.5 * math.pi * (np.arange(n) + 0.5) / n) ** 2
[docs]
@dataclass(frozen=True)
class Sweep:
"""An exponential sine sweep excitation, repeated with silence after each sweep."""
sample_rate: int = 48_000
duration_s: float = 6.0
f_start: float = 20.0
f_stop: float = 20_000.0
level_db: float = -6.0 # peak level, dB re full scale
silence_s: float = 3.0 # after each sweep, for the room to decay
repeats: int = 1
fade_in_s: float = 0.05
fade_out_s: float = 0.005
def __post_init__(self) -> None:
if not 0 < self.f_start < self.f_stop < self.sample_rate / 2:
raise ValueError("need 0 < f_start < f_stop < sample_rate / 2")
if self.duration_s <= 0 or self.silence_s < 0 or self.repeats < 1:
raise ValueError("need duration_s > 0, silence_s >= 0 and repeats >= 1")
@property
def rate(self) -> float:
"""L of x(t) = sin(2 pi f_start L exp(t / L)), rounded so that harmonics stay in
phase with the fundamental (the synchronized sweep)."""
ratio = math.log(self.f_stop / self.f_start)
cycles = max(1, round(self.f_start * self.duration_s / ratio))
return cycles / self.f_start
@property
def sweep_length(self) -> int:
"""Samples in one sweep (the duration after synchronization)."""
return int(round(self.rate * math.log(self.f_stop / self.f_start) * self.sample_rate))
@property
def period(self) -> int:
"""Samples from one sweep's start to the next."""
return self.sweep_length + int(round(self.silence_s * self.sample_rate))
[docs]
def harmonic_delay_s(self, order: int) -> float:
"""How far before the linear response the ``order``-th harmonic's response lands."""
return self.rate * math.log(order)
[docs]
def sweep(self) -> np.ndarray:
"""One sweep, faded in and out."""
t = np.arange(self.sweep_length) / self.sample_rate
x = np.sin(2.0 * math.pi * self.f_start * self.rate * np.exp(t / self.rate))
n_in = min(int(round(self.fade_in_s * self.sample_rate)), len(x) // 2)
n_out = min(int(round(self.fade_out_s * self.sample_rate)), len(x) // 2)
if n_in:
x[:n_in] *= _ramp(n_in)
if n_out:
x[-n_out:] *= _ramp(n_out)[::-1]
return x * 10.0 ** (self.level_db / 20.0)
[docs]
def signal(self) -> np.ndarray:
"""The whole excitation: every repeat, each followed by its silence."""
out = np.zeros(self.period * self.repeats)
one = self.sweep()
for k in range(self.repeats):
out[k * self.period : k * self.period + len(one)] = one
return out
[docs]
def save(self, path: str | Path) -> None:
"""Write the excitation as a float WAV and its settings next to it as JSON."""
from acoustic_spaces.audio import write_wav
path = Path(path)
write_wav(path, self.signal(), self.sample_rate)
path.with_suffix(".json").write_text(
json.dumps(asdict(self), indent=2) + "\n", encoding="utf-8"
)
[docs]
@classmethod
def load(cls, path: str | Path) -> Sweep:
"""Read the settings of a saved excitation (its .json, or the .wav next to it)."""
data = json.loads(Path(path).with_suffix(".json").read_text(encoding="utf-8"))
return cls(**data)
def _band_regularisation(n_fft: int, sweep: Sweep) -> np.ndarray:
"""Small inside the swept band, large outside, with half-octave transitions."""
f = np.fft.rfftfreq(n_fft, 1.0 / sweep.sample_rate)
log_f = np.log2(np.maximum(f, 1e-6))
below = np.clip((np.log2(sweep.f_start) - log_f) / 0.5, 0.0, 1.0)
above = np.clip((log_f - np.log2(sweep.f_stop)) / 0.5, 0.0, 1.0)
out_of_band = np.sin(0.5 * math.pi * np.maximum(below, above)) ** 2
return _EPS_IN + (_EPS_OUT - _EPS_IN) * out_of_band
[docs]
def deconvolve(
recording: np.ndarray,
sweep: Sweep,
length_s: float | None = None,
reference: np.ndarray | None = None,
) -> np.ndarray:
"""Impulse responses (samples, channels) from a recording of ``sweep.signal()``.
``recording`` is (samples,) or (samples, channels), starting when playback started.
Each repeat is deconvolved and the repeats are averaged. ``length_s`` defaults to
the silence after each sweep, and a longer one is cut. With repeats, it is cut to
the silence: the next sweep's harmonic distortion lands right after it. With one
sweep, it is cut to the recording's length less the sweep's, beyond which the
recording lacks the response's high frequencies; for a recording as long as the
excitation, that is the silence too. ``reference`` replaces the generated sweep, for
instance with a loopback recording of one sweep: (samples,) or (samples, 1), as
:func:`~acoustic_spaces.audio.read_wav` gives a mono file.
"""
recording = np.asarray(recording, dtype=float)
if recording.ndim == 1:
recording = recording[:, None]
excitation = sweep.sweep() if reference is None else np.asarray(reference, dtype=float)
if excitation.ndim == 2 and excitation.shape[1] == 1:
excitation = excitation[:, 0]
if excitation.ndim != 1:
raise ValueError("the reference must have one channel: (samples,) or (samples, 1)")
needed = sweep.period * sweep.repeats
if len(recording) < needed:
recording = np.pad(recording, ((0, needed - len(recording)), (0, 0)))
# The next sweep's harmonic n lands L ln n before its linear response, a period on:
# at a lag of the silence for n = f_stop / f_start, later for lower n. A response
# holds frequency f up to a lag L ln(f / f_start) before the recording ends, its
# whole band up to a sweep's length before.
end = sweep.period if sweep.repeats > 1 else len(recording)
length = int(round((sweep.silence_s if length_s is None else length_s) * sweep.sample_rate))
length = max(1, min(length, end - sweep.sweep_length))
n_fft = 1 << int(math.ceil(math.log2(len(recording) + len(excitation))))
x = np.fft.rfft(excitation, n_fft)
power = np.abs(x) ** 2
inverse = np.conj(x) / (power + _band_regularisation(n_fft, sweep) * power.max())
full = np.fft.irfft(np.fft.rfft(recording, n_fft, axis=0) * inverse[:, None], n_fft, axis=0)
out = np.zeros((length, recording.shape[1]))
for k in range(sweep.repeats):
start = k * sweep.period
out += full[start : start + length]
return out / sweep.repeats
[docs]
@dataclass
class Measurement:
"""Measured impulse responses, one column per microphone."""
impulse_responses: np.ndarray # (samples, channels)
sample_rate: int
recording: np.ndarray # (samples, channels), raw
sweep: Sweep
#: Round-trip latency removed using the loopback channel (s), or None.
latency_s: float | None = None
PlayRecord = Callable[[np.ndarray, int, Sequence[int], Sequence[int], object], np.ndarray]
def _sounddevice():
try:
import sounddevice
except (ImportError, OSError) as exc: # OSError: PortAudio library missing
raise ImportError(
f"playing and recording needs sounddevice: {install_hint('measure')}"
) from exc
return sounddevice
[docs]
def play_and_record(
signal: np.ndarray,
sample_rate: int,
outputs: Sequence[int],
inputs: Sequence[int],
device: object = None,
) -> np.ndarray:
"""Play ``signal`` on the output channels and record the inputs (1-based channels).
Returns (samples, len(inputs)), as long as the signal.
"""
sd = _sounddevice()
out = np.repeat(np.asarray(signal, dtype=np.float32)[:, None], len(outputs), axis=1)
recorded = sd.playrec(
out,
samplerate=sample_rate,
input_mapping=list(inputs),
output_mapping=list(outputs),
device=device,
blocking=True,
)
return np.asarray(recorded, dtype=float)
[docs]
def list_devices() -> str:
"""The audio devices sounddevice sees, as text."""
return str(_sounddevice().query_devices())
[docs]
def measure(
sweep: Sweep,
*,
inputs: Sequence[int] = (1,),
output: int = 1,
loopback: int | None = None,
device: object = None,
length_s: float | None = None,
play_record: PlayRecord | None = None,
) -> Measurement:
"""Play ``sweep`` on one output, record ``inputs`` and deconvolve them.
Channels are 1-based. With ``loopback`` (an input wired to the output), the latency
of the audio interface is measured on it and removed from every response.
``play_record`` replaces the audio device, for tests or other audio back ends.
"""
play_record = play_record or play_and_record
channels = list(inputs) + ([loopback] if loopback is not None else [])
recording = play_record(sweep.signal(), sweep.sample_rate, [output], channels, device)
recording = np.asarray(recording, dtype=float).reshape(len(recording), len(channels))
responses = deconvolve(recording, sweep, length_s=length_s)
latency = None
if loopback is not None:
responses, lag = remove_latency(responses, len(channels) - 1)
latency = lag / sweep.sample_rate
return Measurement(
impulse_responses=responses,
sample_rate=sweep.sample_rate,
recording=recording,
sweep=sweep,
latency_s=latency,
)
[docs]
def remove_latency(responses: np.ndarray, loopback: int) -> tuple[np.ndarray, int]:
"""Move responses (samples, channels) earlier by the delay of a loopback channel.
``loopback`` is the 0-based column of the loopback response, which is dropped. Returns
the other columns, padded with zeros at the end, and the delay in samples.
"""
responses = np.asarray(responses, dtype=float)
lag = int(np.argmax(np.abs(responses[:, loopback])))
others = np.delete(responses, loopback, axis=1)
return np.vstack([others[lag:], np.zeros((lag, others.shape[1]))]), lag
__all__ = [
"Measurement",
"Sweep",
"deconvolve",
"list_devices",
"measure",
"play_and_record",
"remove_latency",
]