AcousTools: Open-Source Acoustic Toolkit

• AcousTools is a suite of open-source toolkits designed for quantitative acoustic measurement, employing methods like spectral safeguarding and advanced decomposition.
• It uses robust signal processing algorithms to estimate impulse responses and isolate linear, signal-dependent, and random noise components.
• The toolkit integrates modular workflows from real-time measurement and batch processing to full-stack acoustic holography with device control and underwater feature extraction.

AcousTools refers to a family of open-source toolkits and libraries designed for rigorous quantitative analysis, measurement, and control in acoustics. These tools collectively address distinct application areas: real-time acoustic system measurement using arbitrary sounds, feature extraction in long-term underwater recordings, and full-stack acoustic holography including physical device control. Implementations unify advanced spectral algorithms, robust decomposition/formulation strategies, and direct hardware or streaming data workflows across their domains.

1. Signal Safeguarding and Generalized Acoustic Measurement

AcousTools, as described in "Simultaneous Measurement of Multiple Acoustic Attributes Using Structured Periodic Test Signals Including Music and Other Sound Materials" and expanded in "Sound Safeguarding for Acoustic Measurement Using Any Sounds: Tools and Applications," introduces a unified method for acoustic system characterization using arbitrary audio as test signals (Kawahara et al., 2023, Kawahara et al., 11 Jul 2025). The key innovation is spectrum "safeguarding," in which the periodic test signal is modified such that its discrete Fourier transform (DFT) magnitude at all frequency bins exceeds a specified threshold $\theta[k]$. This prevents division-by-near-zero when deconvolving system response, which is a longstanding issue when using non-synthetic or spectrally sparse test signals.

Given a periodic signal $x[n]$ (period $L$), define its DFT $X[k]$. Construct the safeguarded spectrum:

$$X_{\mathrm{s}}[k] = \begin{cases} \dfrac{\theta[k]\,X[k]}{|X[k]|}, & 0 < |X[k]| < \theta[k] \ X[k], & |X[k]|\geq \theta[k] \ \theta[k], & X[k] = 0 \end{cases}$$

The time-domain safeguarded signal $\tilde{x}[n]$ is obtained by inverse DFT of $X_{\mathrm{s}}[k]$ and tiled periodically. This construct ensures robust downstream division for transfer function estimation, even in the presence of colored noise or test signals with spectral gaps.

Special cases include classical swept-sine, MLS, and CAPRICEP signals. This unification allows practitioners to use ecologically valid or arbitrary sounds (music, speech, noise shaped to specific spectra) for impulse response (IR) measurement, room acoustics, and related applications.

2. Three-Component Decomposition and Measurement Stages

AcousTools decomposes any observed system output $y[n]$ according to:

$$y[n] = (h * x)[n] + v_{\rm SDTI}[n] + v_{\rm RTV}[n], \quad n=0,\dots,L-1$$

where:

• $x[n]$ is the known (periodic, safeguarded) test signal,
• $h[n]$ is the system's linear time-invariant (LTI) impulse response,
• $v_{\rm SDTI}[n]$ is the signal-dependent, time-invariant (SDTI) component, and
• $v_{\rm RTV}[n]$ is the random, time-varying (RTV; stochastic, uncorrelated across periods) component.

The measurement algorithm consists of three stages:

1. Estimation of $h[n]$: Via deconvolution in the frequency domain, often repeated across periods and averaged to enhance SNR:

$$H[k] = \frac{\mathcal{F}[y[n]]}{\mathcal{F}[x[n]]}, \quad h_\text{est}[n] = \mathcal{F}^{-1}\{H[k]\}$$

$$\overline{h}[n] = \frac{1}{P} \sum_{p=1}^P h_\text{est}^{(p)}[n]$$

1. Isolation of RTV: The sample standard deviation $\sigma_{\rm RTV}[n]$ across $P$ periods quantifies period-to-period noise.
2. Measurement of SDTI: Using various $Q$ different test signals $x_q[n]$, the SDTI is measured by the deviation of each $\overline{h}_q[n]$ from their mean across $q$.

An orthogonal encoding exploiting Hadamard matrices (e.g., Walsh–Hadamard basis, as in CAPRICEP) enables simultaneous acquisition of multiple IRs. This allows efficient, parallelized nonlinearity and distortion measurements from a single "superposed" test sequence.

3. AcousTools Library Structure and Practical Workflows

In practice, the AcousTools suite (sometimes referred to as "RHAPSODEE tools")—as documented in (Kawahara et al., 11 Jul 2025)—is implemented in a modular form as command-line executables, a Python package, and a minimal GUI layer. The principal modules are:

• Preparation: Safeguards and exports arbitrary input sounds for measurement.
• Interactive / Real-time Measurement: GUI-based or headless tool streams safeguarded test signals, records responses, and computes IR estimates in real time.
• Batch/Automated Measurement: Designed for unattended operation, repeatedly measures and logs IRs.
• Report Generation: Parses logs and metadata, generating standardized reports (PDF/HTML) containing plots of frequency response, RT60, distortion, and more.

A typical workflow involves sound preparation, interactive measurement with real-time feedback, followed by offline or automated report generation. The software stack is built with numpy/scipy, sounddevice (PortAudio backend), PyQt5/PySide2 for GUI, and Jinja2+matplotlib (or weasyprint/wkhtmltopdf) for reporting.

Performance metrics include GUI update latency (~30 ms for $N\sim65,536$ point FFT), IR estimation accuracy (within ±0.5 dB over 50 Hz–16 kHz in room trials), and robust operation at background noise levels up to ~45 dBA.

4. Acoustic Holography: Full-Stack Modeling and Device Control

AcousTools further denotes a "full-stack" Python-based acoustic holography library (Mukherjee et al., 10 Nov 2025), supporting every stage from geometrical setup to real-world hardware streaming. The architectural modules are:

1. Setup & Configuration: Declarative creation of transducer arrays (e.g., mesh import or library presets), spatial target sets $\{\mathbf{z}_n\}$, and acoustic parameters (frequency $f$, $c_0$, etc.).
2. Acoustic Propagation Modeling: Implements both free-field (Rayleigh integral/piston model) and scattering-aware (BEM) propagators, returning dense mappings $A\in\mathbb{C}^{N\times T}$ for $N$ targets and $T$ transducers.
3. Transducer Phase Retrieval: Offers projective (Gerchberg–Saxton, GS-PAT, weighted GS) and gradient-based (explicit/implicit) solvers to compute transducer excitations $x$ under phase or amplitude constraints.
4. Sound Field Analysis: Provides metrics including pressure, phase, Gor’kov potential, radiation force, and stiffness, with both analytical and finite-difference gradients.
5. Hardware Control: Exposes driver interfaces for direct hardware streaming (e.g., OpenMPD boards), enabling real-time physicalization of computed holograms.

This library leverages Python and PyTorch for high-level logic and GPU acceleration, with domain-specific implementations for analytical propagation, phase retrieval, and device control. All modules are accessible via a principled API (example invocations and end-to-end workflows are given in the corpus).

Performance benchmarks indicate projective solvers (GS-PAT) operate at 100 Hz–1 kHz for $N=100$ targets on desktop GPUs, while Gor’kov potential calculations reach ~4,234 solutions per second (analytical piston) and ~1,922 solutions per second (finite difference) for 3,000 points. Only AcousTools covers the entire pipeline with BEM, multiple solvers, sound field analysis, and physical device integration in a single codebase.

5. Temporal Feature Extraction in Long-Term Hydrophone Recordings

AcousTools, as described in the context of underwater seismic survey analysis, is also a toolkit for segmentation and high-throughput feature extraction from long-form ocean acoustic recordings (Dugan et al., 2016). The toolkit's architecture is:

• Data Ingestion: Block-wise streaming from disk/network
• Calibration: Converts raw digital samples $D(t)$ to pressure $p(t)=D(t)\cdot K$
• M-Weighting Filter Bank: Linear, low-frequency cetacean (LFC), and mid-frequency cetacean (MFC) bands via biquad filtering
• Pulse Detection: Energy-based location of airgun pulses and computation of inter-pulse intervals (IPIs)
• Segmentation: Early-time window (5–95% energy of pulse), late-time windows (fixed length/N windows)
• Feature Extraction: Computes a suite of 183 features per event per weighting stream, including:
  • Peak/peak-to-peak pressures
  • RMS, SPL, SEL, CSEL, $L_{\mathrm{EQ}}$, percentile levels (e.g., $L_{90}$)
• Output: Features saved to HDF5/Parquet for further analysis

The mathematical definitions for these measures are standard, e.g.,

$$L_{\mathrm{SPL}} = 20\log_{10}(p_{\mathrm{rms}}/p_0),\quad SEL = 10\log_{10}\left(\frac{1}{p_0^2} \int p^2(t) dt\right)$$

Implementations in Python (NumPy/SciPy, HDF5, dask for parallelization) or compiled C++ for inner loops enable processing at scale: e.g., 147 million features in 18 hours (parallel, 12 cores) for an entire Arctic field campaign.

6. Extensibility, Integrations, and Best Practices

The various AcousTools codebases are distributed under permissive open-source licenses, supporting cross-platform builds, scripting integration (e.g., command-line tools callable from MATLAB/Octave or Python), and modular APIs for extension. Command-line, GUI, and Pythonic workflows are supported for both measurement and reporting.

Table: Implementation and Application Domains

Tool Variant / Paper	Main Implementation Language(s)	Primary Application Domains
Measurement & Safeguarding (Kawahara et al., 2023, Kawahara et al., 11 Jul 2025)	Python, minimal GUI (PyQt5)	Room acoustics, device/room IR, objective estimator eval
Holography Full-Stack (Mukherjee et al., 10 Nov 2025)	Python, PyTorch, native hardware	Acoustic levitation, haptics, volumetric displays
Underwater Feature Extraction (Dugan et al., 2016)	Python/C++	Marine noise, impact assessment, seismic surveys

Recommended practices include:

• Pre-calibrate acquisition chains
• Match safeguarded FFT length and zero-padding to decay time
• Use frequency-shaped thresholds to prevent spectral "holes"
• For spectral features/local processing, augment with custom threshold functions or windowing schemes

The design aligns with reproducible research: all measurement steps and safeguarding parameters are logged for report generation and downstream analysis.

7. Summary and Significance

AcousTools, in its various incarnations, unifies state-of-the-art acoustic measurement strategies—in situ system characterization, acoustic feature mining, and holographic sound field control—around transparent, mathematically robust algorithms and open-source, extensible codebases. Its safeguarding paradigm generalizes standard excitation signals to arbitrary sound material, broadening the ecological and practical scope of acoustic measurement. In holography, it uniquely spans system abstraction to hardware streaming with both analytical and data-driven solvers.

Adoption of these tools permits precise, reproducible acoustic analysis across laboratory, field, and real-time interactive contexts, with direct applicability in disciplines ranging from architectural acoustics and signal processing to biomedical manipulation and ecological monitoring. Each toolchain emphasizes interpretability, extensibility, and integration with broader computational and experimental workflows.