Open spatial-audio building blocks for smart glasses and hearables. 面向智能穿戴设备的开箱即用多麦阵列工具包。
HearWeave is a lightweight Python toolkit for prototyping microphone-array processing on AI glasses, earbuds, and other smart wearable devices. It packages readable reference implementations, wearable geometry presets, deterministic synthetic data, and visualization helpers in one repository.
The animation is a deterministic visual walkthrough of the checked-in synthetic scene—not a runtime trace or real-device recording. It shows the declared microphone geometry, channel delays, SRP-PHAT direction score, and the corresponding 2 kHz delay-and-sum beam.
General speech-enhancement repositories usually assume linear or circular tabletop arrays. Wearable devices have different constraints: temple microphones, left/right cooperation, small asymmetric sub-arrays, head shadowing, and strict compute budgets. HearWeave starts from those device geometries while keeping every baseline easy to inspect.
- Smart-glasses 4-microphone and asymmetric 6-microphone earbud presets
- Far-field multi-channel scene simulation with microphone-mismatch modelling
- Delay-and-sum and frequency-domain MVDR beamforming
- Streaming block-based delay-and-sum with verified sample-exact latency
- GCC-PHAT pairwise delay estimation
- Grid-based azimuth localization and band-limited, coherence-weighted SRP-PHAT
- Binaural coherence enhancement baseline
- SNR and SI-SDR metrics
- Geometry, beampattern, and localization visualizations
- Synthetic smart-glasses sample scene with no recorded speech
- Validated JSON + mono-WAV adapter for measured multichannel recordings
- A step-by-step tutorial and a full algorithm reference with derivations and parameter guidance
git clone https://github.com/WonderfulClaire/HearWeave.git
cd HearWeave
python --version # HearWeave requires Python 3.10+
python -m pip install --upgrade pip
python -m pip install .
hearweave-demo --output demo-outputThis installs the same wheel-style package an end user receives. Contributors who want an
editable checkout can instead run python -m pip install -e ".[dev]" after upgrading pip.
import numpy as np
from hearweave import delay_and_sum, glasses_4mic, srp_phat
scene = np.load("datasets/simulated_glasses_scene.npz")
geometry = glasses_4mic()
signals = scene["microphone_signals"]
sample_rate = int(scene["sample_rate_hz"])
azimuth, scores, grid = srp_phat(signals, geometry, sample_rate)
enhanced = delay_and_sum(signals, geometry, sample_rate, azimuth)
print(f"estimated direction: {azimuth:.1f}°")New to microphone arrays? Start with the tutorial — seven copy-pasteable steps from geometry to a robustness experiment, all synthetic and reproducible.
The checked-in scene is a deterministic smoke test: a synthetic speech-like probe reaches the glasses array from 35° with independent channel noise. It is not a benchmark or real-device accuracy claim.
Regenerate the dataset and figures with:
python -m pip install .
python scripts/generate_assets.py
python scripts/generate_showcase.pyA reproducible synthetic benchmark compares delay-and-sum against MVDR on a smart-glasses scene with a target at 35°, an equal-power directional interferer at −60°, and isotropic channel noise at a swept input SNR.
-
Full methodology, the results table, and the curve:
docs/beambench.md. -
Reproducible figures (regenerated by the script):
-
Regenerate everything (table, curve, and the input/output waveform comparison) with:
python scripts/beambench.py
Results are seeded and fully deterministic.
requires a different Python: checkpython --version; macOS may still mappython3to Python 3.9. Create the environment with Python 3.10 or newer.editable mode currently requires a setuptools-based build: the environment has an old pip. Use the end-user commandpython -m pip install ., or upgrade pip before an editable install.hearweave-demo: command not found: make sure the environment used for installation is active, or runpython -m hearweave.cli --output demo-output.
- Wearable geometry first — coordinates and device assumptions are explicit.
- Readable baselines — reference code is suitable for learning and experiment scaffolding.
- Reproducible artifacts — demos have fixed seeds and synthetic redistributable data.
- Honest boundaries — simulations are never presented as real-device evidence.
- Composable APIs — geometry, simulation, localization, enhancement, metrics, and plots stay separable.
Read Algorithms and assumptions before using results in a paper or product comparison — it now covers the mathematics, parameter cheat sheet, complexity, and failure modes of every shipped algorithm.
To connect measured hardware without guessing channel order or geometry, use the real-recording manifest and evaluation protocol. The public repository contains only a manifest template and synthetic tests—no private or third-party recordings.
HearWeave is research and prototyping software—not a hearing aid, safety device, or clinically validated enhancement system. The first simulator does not model rooms, head-related transfer functions, microphone mismatch, or clock drift. Those are intentional extension points, not hidden assumptions.
- SRP-PHAT localization (v0.2, band-limited + coherence-weighted)
- Microphone-mismatch simulation (v0.2)
- Streaming/block-processing interfaces (v0.2, delay-and-sum)
- BeamBench integration examples (v0.3, reproducible DAS vs MVDR on synthetic glasses scene with interferer)
- PyPI package and Trusted Publishing (v0.3)
- Measured and simulated wearable RIR loaders
- Multi-source tracking
- Head-shadow simulation
- Streaming MVDR and block-based localization
- ONNX-friendly low-compute baselines
- Real-device recording manifest, validated WAV adapter, and evaluation protocol
- Measured dataset releases and device-specific calibration adapters
New device layouts, algorithms, tests, and reproducible evaluation fixtures are welcome. See CONTRIBUTING.md. Security or privacy issues should use the private reporting flow.
If HearWeave supports published work, the repository includes a machine-readable citation file.
This section tracks publications, technical reports, and notes that build on or cite HearWeave. Submit additions via a pull request that links the artifact and adds a one-line description.
| Type | Title | Venue / year | Link |
|---|---|---|---|
| Technical report | BeamBench: a reproducible DAS vs MVDR benchmark on synthetic smart-glasses scenes | v0.3, 2026 | docs/beambench.md |
| Documentation | Algorithms, parameter cheat sheet, complexity, and failure modes | v0.2, 2026 | docs/ALGORITHMS.md |
| Documentation | Step-by-step end-to-end tutorial (7 stages) | v0.2, 2026 | docs/TUTORIAL.md |
| Documentation | Real-device recording manifest and evaluation protocol | v0.3, 2026 | docs/REAL_RECORDINGS.md |
To add a paper or report: open a PR that appends a row with the venue, year, and a stable link (DOI, arXiv ID, or repository path).