API

Compute directivity gain for a pattern given cos(theta).

Simulate a static or dynamic scene with the image-source method.

Convolve signals with static RIRs (supports multi-source/mic).

Parameters:

Returns:

Examples:

y = convolve_rir(signal, rirs)

Convolve a 1D signal with a 1D RIR using FFT.

Parameters:

Returns:

Examples:

y = fft_convolve(signal, rir)

Create a two-mic binaural layout around a center point.

Create an equally spaced circular microphone array.

Clamp positions to remain inside the room with a margin.

Create the mh acoustics Eigenmike em32 geometry (3D only).

Create the mh acoustics Eigenmike em64 geometry (3D only).

Create an equally spaced linear microphone array.

Interpolate a line at explicit normalized progress values.

progress makes the trajectory's time grid explicit. For a dynamic RIR scene, obtain it from FrameSchedule.normalized_progress so every geometry frame is evaluated at its exact sample start.

Create a regular polyhedron microphone array (3D only).

Sample random positions within a room with a safety margin.

Sample random positions with a minimum distance from a center point.

Render a GIF showing source/mic trajectories.

Render an MP4 showing source/mic trajectories.

When mux_audio is enabled and mixture_path is given, a stereo track is added with ffmpeg using the requested channel indices. The video canvas defaults to HD (1280x720).

Plot source and mic trajectories within a room.

If trajectories are static, only positions are plotted.

Examples:

ax = plot_scene_dynamic(
    room=[6.0, 4.0, 3.0],
    src_traj=src_traj,
    mic_traj=mic_traj,
)

Plot a static room with source and mic positions.

Examples:

ax = plot_scene_static(
    room=[6.0, 4.0, 3.0],
    sources=[[1.0, 2.0, 1.5]],
    mics=[[2.0, 2.0, 1.5]],
)

Plot static and dynamic scenes and save images to disk.

Render trajectory GIFs.

Save static layout images with explicit 2D/3D filenames.

Plot and save scene images.

Render trajectory MP4 videos.

Output names follow oobss-compatible conventions: - room_layout_2d.mp4 - room_layout_3d.mp4 (3D rooms when save_3d is enabled)

Build JSON-serializable metadata for a simulation output.

Examples:

metadata = build_metadata(
    room=room,
    sources=sources,
    mics=mics,
    rirs=rirs,
    src_traj=src_traj,
    mic_traj=mic_traj,
    signal_len=signal.shape[-1],
)
save_metadata_json(Path("outputs/scene_metadata.json"), metadata)

Build metadata from a scene-oriented simulation result.

Return metadata for an audio file (wav/flac/other supported by soundfile).

Return metadata for a wav file.

This entry point is wav-only. For non-wav formats, use torchrir.io.info_audio.

Load an audio file (wav/flac/other supported by soundfile).

Load audio and metadata without closing a caller-owned stream.

Load a wav file and return mono audio and sample rate.

This entry point is wav-only. For non-wav formats, use torchrir.io.load_audio.

Save dataset attribution and modification notes to a text file.

Save a mono or multi-channel audio file without changing its gain.

Use normalize=True only when independent peak normalization is intended. WAV destinations default to the FLOAT subtype. Other formats reject out-of-range samples before their integer/compressed encoding can clip. For related stems and mixtures, apply one common scale before saving.

Save audio, preserving subtype only when the container is unchanged.

Save metadata as JSON to the given path.

Examples:

save_metadata_json(Path("outputs/scene_metadata.json"), metadata)

Build and save metadata from an RIRResult.

Save scene audio without applying implicit gain normalization.

Build and save scene metadata JSON to the output directory.

Save a wav file without changing its gain.

With no explicit subtype, WAV output uses 32-bit floating-point samples so values outside [-1, 1] are not clipped. Set normalize=True explicitly to peak-normalize. This entry point is wav-only; for non-wav formats, use torchrir.io.save_audio.

Return a torchrir logger, namespaced under the torchrir root.

Examples:

logger = get_logger("examples.static")

Configure and return the root torchrir logger.

Examples:

logger = setup_logging(LoggingConfig(level="DEBUG"))
logger.info("ready")

Add common output/plot/GIF arguments to a parser.

Convert numeric input to a real floating-point tensor.

Integer inputs are promoted to PyTorch's default floating dtype when no dtype is requested. Explicit non-floating and complex dtypes are rejected because the geometry and acoustic kernels require real floating values.

Convert a value to a tensor while preserving device/dtype when possible.

Convert attenuation (dB) to time based on T60.

Examples:

t = attenuation_db_to_time_sabine(att_db=60.0, t60=0.4)

Validate room size dimensionality (2D or 3D).

Estimate uniform wall reflection coefficients with Sabine's formula.

The 2D model uses 12 ln(10) / c with room area and perimeter. The 3D model uses 24 ln(10) / c with room volume and surface area. A requested T60 that would require an energy absorption coefficient greater than one is physically infeasible and raises ValueError instead of being clipped.

Examples:

beta = estimate_beta_from_t60(torch.tensor([6.0, 4.0, 3.0]), t60=0.4)

Estimate image counts per dimension needed to cover tmax.

Examples:

nb_img = estimate_image_counts_from_tmax(0.3, torch.tensor([6.0, 4.0, 3.0]))

Estimate T60 from reflection coefficients using Sabine's formula.

Reflection coefficients are pressure-amplitude ratios in [0, 1]. The corresponding energy absorption is 1 - beta**2. Perfectly reflecting walls therefore produce an infinite T60.

Examples:

t60 = estimate_t60_from_beta(torch.tensor([6.0, 4.0, 3.0]), beta=torch.full((6,), 0.9))

Extend 2D room size to 3D by adding a dummy z dimension.

Normalize non-zero orientation vectors.

Convert unambiguous angle/vector representations to unit vectors.

In 2D, angles are scalar or have shape (..., 1) and vectors have shape (..., 2). In 3D, azimuth/elevation pairs have shape (..., 2) and vectors have shape (..., 3). A one-dimensional 2D tensor with two elements is therefore always one vector, never two per-entity angles.

Resolve a device string (including 'auto') into a torch.device.

Falls back to CPU when the requested backend is unavailable.

Examples:

device = resolve_device("auto")

Return attribution info for a supported dataset key.

Build and publish a staged dynamic CMU ARCTIC dataset with rollback.

Builds for the same target are serialized before any expensive scene work. Every scene is written below an owned sibling workspace, and the target is created or replaced only after the complete build succeeds. If publication fails, the previous target is restored before the error is reported.

Select unique speakers for the requested number of sources.

Examples:

rng = random.Random(0)
speakers = choose_speakers(available_speakers, num_sources=2, rng=rng)

Return supported speakers, or locally installed speakers below root.

Collate DatasetItem entries into a padded batch.

Parameters:

Returns:

Return concise modification notes for generated outputs.

Load and concatenate utterances for each speaker into fixed-length signals.

Examples:

from pathlib import Path
from torchrir.datasets import CmuArcticDataset, cmu_arctic_speakers
rng = random.Random(0)
root = Path("datasets/cmu_arctic")
signals, fs, info = load_dataset_sources(
    dataset_factory=lambda spk: CmuArcticDataset(root, speaker=spk, download=True),
    speakers=cmu_arctic_speakers(),
    num_sources=2,
    duration_s=10.0,
    rng=rng,
)