torchrir 0.6.0

PyTorch-based room impulse response (RIR) simulation toolkit for static and dynamic scenes.

TorchRIR

PyTorch-based room impulse response (RIR) simulation toolkit focused on a clean, modern API with GPU support. This project has been substantially assisted by AI using Codex.

[!WARNING] TorchRIR is under active development and may contain bugs or breaking changes. Please validate results for your use case. If you find bugs or have feature requests, please open an issue. Contributions are welcome.

Installation

pip install torchrir

CUDA CI (GitHub Actions)

• CUDA tests run in .github/workflows/cuda-ci.yml on a self-hosted runner with labels: self-hosted, linux, x64, cuda.
• The workflow validates installation via uv sync --group test, checks torch.cuda.is_available(), runs tests/test_device_parity.py with -k cuda, and then tries to install gpuRIR from GitHub.
• If gpuRIR installs successfully, the workflow runs tests/test_compare_gpurir.py (static + dynamic RIR comparisons). If installation fails, those comparison tests are skipped without failing the whole CUDA CI job.

Examples

• examples/static.py: fixed sources/mics with configurable mic count (default: binaural).
  uv run python examples/static.py --plot
• examples/dynamic_src.py: moving sources, fixed mics.
  uv run python examples/dynamic_src.py --plot
• examples/dynamic_mic.py: fixed sources, moving mics.
  uv run python examples/dynamic_mic.py --plot
• examples/cli.py: unified CLI for static/dynamic scenes, JSON/YAML configs.
  uv run python examples/cli.py --mode static --plot
• examples/build_dynamic_dataset.py: small dynamic dataset generator (CMU ARCTIC / LibriSpeech; fixed room/mics, randomized source motion).
  uv run python examples/build_dynamic_dataset.py --dataset cmu_arctic --num-scenes 4 --num-sources 2
• examples/benchmark_device.py: CPU/GPU benchmark for RIR simulation.
  uv run python examples/benchmark_device.py --dynamic

Core API Overview

• Geometry: Room, Source, MicrophoneArray
• Static RIR: torchrir.sim.simulate_rir
• Dynamic RIR: torchrir.sim.simulate_dynamic_rir
• Dynamic convolution: torchrir.signal.DynamicConvolver
• Metadata export: torchrir.io.build_metadata, torchrir.io.save_metadata_json

Module Layout (for contributors)

• torchrir.sim: simulation backends (ISM implementation lives under torchrir.sim.ism)
• torchrir.signal: convolution utilities and dynamic convolver
• torchrir.geometry: array geometries, sampling, trajectories
• torchrir.viz: plotting and animation helpers
• torchrir.models: room/scene/result data models
• torchrir.io: audio I/O and metadata serialization (wav-only load/save/info with backend selection)
• torchrir.util: shared math/tensor/device helpers
• torchrir.logging: logging utilities
• torchrir.config: simulation configuration objects

from torchrir import MicrophoneArray, Room, Source
from torchrir.sim import simulate_rir
from torchrir.signal import DynamicConvolver

room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
sources = Source.from_positions([[1.0, 2.0, 1.5]])
mics = MicrophoneArray.from_positions([[2.0, 2.0, 1.5]])

rir = simulate_rir(room=room, sources=sources, mics=mics, max_order=6, tmax=0.3)
# For dynamic scenes, compute rirs with torchrir.sim.simulate_dynamic_rir and convolve:
# y = DynamicConvolver(mode="trajectory").convolve(signal, rirs)

For detailed documentation, see the docs under docs/ and Read the Docs.

Future Work

• Ray tracing backend: implement torchrir.experimental.RayTracingSimulator with frequency-dependent absorption/scattering.
• CUDA-native acceleration: introduce dedicated CUDA kernels for large-scale RIR generation.
• Dataset expansion: add additional dataset integrations beyond CMU ARCTIC (see torchrir.experimental.TemplateDataset), including torchaudio datasets (e.g., LibriSpeech, VCTK, LibriTTS, SpeechCommands, CommonVoice, GTZAN, MUSDB-HQ).

Related Libraries

• gpuRIR
• Cross3D
• pyroomacoustics
• rir-generator

Related Library Comparison (Quick View)

Dynamic Simulation

Feature	torchrir	gpuRIR	pyroomacoustics	rir-generator
🎯 Dynamic Sources	✅	🟡 Single-source workflow	🟡 Manual loop	❌
🎤 Dynamic Microphones	✅	❌	🟡 Manual loop	❌
🖥️ CPU	✅	❌	✅	✅
🧮 CUDA	🚧 Coming soon	✅	❌	❌
🍎 MPS	✅	❌	❌	❌
📊 Visualization	✅	❌	✅	❌
🗂️ Dataset Build	✅	❌	🟡 Custom scripts	❌

ISM HPF (RIR High-Pass Filter)

Library	Built-in HPF	Method
torchrir	✅	IIR, zero-phase
gpuRIR	❌	No built-in HPF
rir-generator	✅	Allen & Berkley-style recursive HPF
pyroomacoustics	✅	IIR, zero-phase

ISM Amplitude Scaling (Image-Source Gain)

Library	Typical distance scaling	Notes
torchrir	1/r	Reflection/directivity gains are multiplied, then divided by distance.
gpuRIR	1/(4πr)	Includes explicit free-field 4π factor in image-source amplitude.
rir-generator	1/(4πr)	Core implementation follows 4π free-field normalization.
pyroomacoustics	Usually 1/r in room ISM path	The build_rir_matrix path uses 1/(4πr), so scaling depends on API path.

When comparing raw waveform amplitudes across libraries, a near-constant factor of about 4π can appear between 1/r and 1/(4πr) conventions.

Legend:

• ✅ native support
• 🟡 manual setup
• 🚧 coming soon
• ❌ unavailable

Detailed notes and equations: docs/comparisons.md.