torchrir 0.1.0__tar.gz → 0.1.2__tar.gz

{torchrir-0.1.0 → torchrir-0.1.2}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: torchrir
-Version: 0.1.0
-Summary: Add your description here
+Version: 0.1.2
+Summary: PyTorch-based room impulse response (RIR) simulation toolkit for static and dynamic scenes.
+Project-URL: Repository, https://github.com/taishi-n/torchrir
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -18,6 +19,22 @@ This project has been substantially assisted by AI using Codex.
 ## License
 Apache-2.0. See `LICENSE` and `NOTICE`.
 
+## Installation
+```bash
+pip install torchrir
+```
+
+## Current Capabilities
+- ISM-based static and dynamic RIR simulation (2D/3D shoebox rooms).
+- Directivity patterns: `omni`, `cardioid`, `hypercardioid`, `subcardioid`, `bidir` with orientation handling.
+- Acoustic parameters: `beta` or `t60` (Sabine), optional diffuse tail via `tdiff`.
+- Dynamic convolution via `DynamicConvolver` (`trajectory` or `hop` modes).
+- GPU acceleration for ISM accumulation (CUDA/MPS; MPS disables LUT).
+- Dataset utilities with CMU ARCTIC support and example pipelines.
+- Plotting utilities for static and dynamic scenes.
+- Metadata export helpers for time axis, DOA, and array attributes (JSON-ready).
+- Unified CLI with JSON/YAML config and deterministic flag support.
+
 ## Example Usage
 ```bash
 # CMU ARCTIC + static RIR (fixed sources/mics)
@@ -26,16 +43,22 @@ uv run python examples/static.py --plot
 # Dynamic RIR demos
 uv run python examples/dynamic_mic.py --plot
 uv run python examples/dynamic_src.py --plot
+uv run python examples/dynamic_mic.py --gif
+uv run python examples/dynamic_src.py --gif
 
 # Unified CLI
 uv run python examples/cli.py --mode static --plot
 uv run python examples/cli.py --mode dynamic_mic --plot
 uv run python examples/cli.py --mode dynamic_src --plot
+uv run python examples/cli.py --mode dynamic_mic --gif
+uv run python examples/dynamic_mic.py --gif --gif-fps 12
 
 # Config + deterministic
 uv run python examples/cli.py --mode static --deterministic --seed 123 --config-out outputs/cli.json
 uv run python examples/cli.py --config-in outputs/cli.json
 ```
+GIF FPS is auto-derived from signal duration and RIR steps unless overridden with `--gif-fps`.
+For 3D rooms, an additional `*_3d.gif` is saved.
 YAML configs are supported when `PyYAML` is installed.
 ```bash
 # YAML config
@@ -43,6 +66,24 @@ uv run python examples/cli.py --mode static --config-out outputs/cli.yaml
 uv run python examples/cli.py --config-in outputs/cli.yaml
 ```
 `examples/cli_example.yaml` provides a ready-to-use template.
+Examples also save `*_metadata.json` alongside audio outputs.
+
+```python
+from torchrir import DynamicConvolver, MicrophoneArray, Room, Source, simulate_rir
+
+room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+sources = Source.positions([[1.0, 2.0, 1.5]])
+mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+
+rir = simulate_rir(
+    room=room,
+    sources=sources,
+    mics=mics,
+    max_order=6,
+    tmax=0.3,
+    device="auto",
+)
+```
 
 ```python
 from torchrir import DynamicConvolver
@@ -55,6 +96,20 @@ y = DynamicConvolver(mode="hop", hop=1024).convolve(signal, rirs)
 ```
 Dynamic convolution is exposed via `DynamicConvolver` only (no legacy function wrappers).
 
+## Limitations and Potential Errors
+- Ray tracing and FDTD simulators are placeholders and raise `NotImplementedError`.
+- `TemplateDataset` methods are not implemented and will raise `NotImplementedError`.
+- `simulate_rir`/`simulate_dynamic_rir` require `max_order` (or `SimulationConfig.max_order`) and either `nsample` or `tmax`.
+- Non-`omni` directivity requires orientation; mismatched shapes raise `ValueError`.
+- `beta` must have 4 (2D) or 6 (3D) elements; invalid sizes raise `ValueError`.
+- `simulate_dynamic_rir` requires `src_traj` and `mic_traj` to have matching time steps.
+- Dynamic simulation currently loops per time step; very long trajectories can be slow.
+- MPS disables the sinc LUT path (falls back to direct sinc), which can be slower and slightly different numerically.
+- Deterministic mode is best-effort; some backends may still be non-deterministic.
+- YAML configs require `PyYAML`; otherwise a `ModuleNotFoundError` is raised.
+- CMU ARCTIC downloads require network access.
+- GIF animation output requires Pillow (via matplotlib animation writer).
+
 ### Dataset-agnostic utilities
 ```python
 from torchrir import (
@@ -129,6 +184,7 @@ device, dtype = DeviceSpec(device="auto").resolve()
 
 ## References
 - [gpuRIR](https://github.com/DavidDiazGuerra/gpuRIR)
+- [Cross3D](https://github.com/DavidDiazGuerra/Cross3D)
 - [pyroomacoustics](https://github.com/LCAV/pyroomacoustics)
 - [das-generator](https://github.com/ehabets/das-generator)
 - [rir-generator](https://github.com/audiolabs/rir-generator)
@@ -211,3 +267,5 @@ y = DynamicConvolver(mode="trajectory").convolve(signal, rirs)
 - FDTD backend: implement `FDTDSimulator` with configurable grid resolution and boundary conditions.
 - Dataset expansion: add additional dataset integrations beyond CMU ARCTIC (see `TemplateDataset`).
 - Enhanced acoustics: frequency-dependent absorption and more advanced diffuse tail models.
+- Add microphone and source directivity models similar to gpuRIR/pyroomacoustics.
+- Add regression tests comparing generated RIRs against gpuRIR outputs.

torchrir-0.1.0/src/torchrir.egg-info/PKG-INFO → torchrir-0.1.2/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: torchrir
-Version: 0.1.0
-Summary: Add your description here
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: numpy>=2.2.6
-Requires-Dist: torch>=2.10.0
-Dynamic: license-file
-
 # TorchRIR
 
 PyTorch-based room impulse response (RIR) simulation toolkit focused on a clean, modern API with GPU support.
@@ -18,6 +6,22 @@ This project has been substantially assisted by AI using Codex.
 ## License
 Apache-2.0. See `LICENSE` and `NOTICE`.
 
+## Installation
+```bash
+pip install torchrir
+```
+
+## Current Capabilities
+- ISM-based static and dynamic RIR simulation (2D/3D shoebox rooms).
+- Directivity patterns: `omni`, `cardioid`, `hypercardioid`, `subcardioid`, `bidir` with orientation handling.
+- Acoustic parameters: `beta` or `t60` (Sabine), optional diffuse tail via `tdiff`.
+- Dynamic convolution via `DynamicConvolver` (`trajectory` or `hop` modes).
+- GPU acceleration for ISM accumulation (CUDA/MPS; MPS disables LUT).
+- Dataset utilities with CMU ARCTIC support and example pipelines.
+- Plotting utilities for static and dynamic scenes.
+- Metadata export helpers for time axis, DOA, and array attributes (JSON-ready).
+- Unified CLI with JSON/YAML config and deterministic flag support.
+
 ## Example Usage
 ```bash
 # CMU ARCTIC + static RIR (fixed sources/mics)
@@ -26,16 +30,22 @@ uv run python examples/static.py --plot
 # Dynamic RIR demos
 uv run python examples/dynamic_mic.py --plot
 uv run python examples/dynamic_src.py --plot
+uv run python examples/dynamic_mic.py --gif
+uv run python examples/dynamic_src.py --gif
 
 # Unified CLI
 uv run python examples/cli.py --mode static --plot
 uv run python examples/cli.py --mode dynamic_mic --plot
 uv run python examples/cli.py --mode dynamic_src --plot
+uv run python examples/cli.py --mode dynamic_mic --gif
+uv run python examples/dynamic_mic.py --gif --gif-fps 12
 
 # Config + deterministic
 uv run python examples/cli.py --mode static --deterministic --seed 123 --config-out outputs/cli.json
 uv run python examples/cli.py --config-in outputs/cli.json
 ```
+GIF FPS is auto-derived from signal duration and RIR steps unless overridden with `--gif-fps`.
+For 3D rooms, an additional `*_3d.gif` is saved.
 YAML configs are supported when `PyYAML` is installed.
 ```bash
 # YAML config
@@ -43,6 +53,24 @@ uv run python examples/cli.py --mode static --config-out outputs/cli.yaml
 uv run python examples/cli.py --config-in outputs/cli.yaml
 ```
 `examples/cli_example.yaml` provides a ready-to-use template.
+Examples also save `*_metadata.json` alongside audio outputs.
+
+```python
+from torchrir import DynamicConvolver, MicrophoneArray, Room, Source, simulate_rir
+
+room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+sources = Source.positions([[1.0, 2.0, 1.5]])
+mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+
+rir = simulate_rir(
+    room=room,
+    sources=sources,
+    mics=mics,
+    max_order=6,
+    tmax=0.3,
+    device="auto",
+)
+```
 
 ```python
 from torchrir import DynamicConvolver
@@ -55,6 +83,20 @@ y = DynamicConvolver(mode="hop", hop=1024).convolve(signal, rirs)
 ```
 Dynamic convolution is exposed via `DynamicConvolver` only (no legacy function wrappers).
 
+## Limitations and Potential Errors
+- Ray tracing and FDTD simulators are placeholders and raise `NotImplementedError`.
+- `TemplateDataset` methods are not implemented and will raise `NotImplementedError`.
+- `simulate_rir`/`simulate_dynamic_rir` require `max_order` (or `SimulationConfig.max_order`) and either `nsample` or `tmax`.
+- Non-`omni` directivity requires orientation; mismatched shapes raise `ValueError`.
+- `beta` must have 4 (2D) or 6 (3D) elements; invalid sizes raise `ValueError`.
+- `simulate_dynamic_rir` requires `src_traj` and `mic_traj` to have matching time steps.
+- Dynamic simulation currently loops per time step; very long trajectories can be slow.
+- MPS disables the sinc LUT path (falls back to direct sinc), which can be slower and slightly different numerically.
+- Deterministic mode is best-effort; some backends may still be non-deterministic.
+- YAML configs require `PyYAML`; otherwise a `ModuleNotFoundError` is raised.
+- CMU ARCTIC downloads require network access.
+- GIF animation output requires Pillow (via matplotlib animation writer).
+
 ### Dataset-agnostic utilities
 ```python
 from torchrir import (
@@ -129,6 +171,7 @@ device, dtype = DeviceSpec(device="auto").resolve()
 
 ## References
 - [gpuRIR](https://github.com/DavidDiazGuerra/gpuRIR)
+- [Cross3D](https://github.com/DavidDiazGuerra/Cross3D)
 - [pyroomacoustics](https://github.com/LCAV/pyroomacoustics)
 - [das-generator](https://github.com/ehabets/das-generator)
 - [rir-generator](https://github.com/audiolabs/rir-generator)
@@ -211,3 +254,5 @@ y = DynamicConvolver(mode="trajectory").convolve(signal, rirs)
 - FDTD backend: implement `FDTDSimulator` with configurable grid resolution and boundary conditions.
 - Dataset expansion: add additional dataset integrations beyond CMU ARCTIC (see `TemplateDataset`).
 - Enhanced acoustics: frequency-dependent absorption and more advanced diffuse tail models.
+- Add microphone and source directivity models similar to gpuRIR/pyroomacoustics.
+- Add regression tests comparing generated RIRs against gpuRIR outputs.

torchrir-0.1.2/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "torchrir"
+version = "0.1.2"
+description = "PyTorch-based room impulse response (RIR) simulation toolkit for static and dynamic scenes."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.2.6",
+    "torch>=2.10.0",
+]
+
+[project.urls]
+Repository = "https://github.com/taishi-n/torchrir"
+
+[dependency-groups]
+dev = [
+    "git-cliff>=2.10.1",
+    "matplotlib>=3.10.8",
+    "pillow>=11.2.1",
+    "pyroomacoustics>=0.9.0",
+    "pytest>=9.0.2",
+    "soundfile>=0.13.1",
+    "sphinx>=7.0,<8.2.3",
+    "sphinx-rtd-theme>=2.0.0",
+    "myst-parser>=2.0,<4.0",
+]

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/__init__.py

@@ -4,6 +4,8 @@ from .config import SimulationConfig, default_config
 from .core import simulate_dynamic_rir, simulate_rir
 from .dynamic import DynamicConvolver
 from .logging_utils import LoggingConfig, get_logger, setup_logging
+from .animation import animate_scene_gif
+from .metadata import build_metadata, save_metadata_json
 from .plotting import plot_scene_dynamic, plot_scene_static
 from .plotting_utils import plot_scene_and_save
 from .room import MicrophoneArray, Room, Source
@@ -61,6 +63,8 @@ __all__ = [
     "get_logger",
     "list_cmu_arctic_speakers",
     "LoggingConfig",
+    "animate_scene_gif",
+    "build_metadata",
     "resolve_device",
     "SentenceLike",
     "load_dataset_sources",
@@ -75,6 +79,7 @@ __all__ = [
     "plot_scene_and_save",
     "plot_scene_static",
     "save_wav",
+    "save_metadata_json",
     "Scene",
     "setup_logging",
     "SimulationConfig",

torchrir-0.1.2/src/torchrir/animation.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+"""Animation helpers for dynamic scenes."""
+
+from pathlib import Path
+from typing import Optional, Sequence
+
+import torch
+
+from .plotting_utils import _positions_to_cpu, _to_cpu, _traj_steps, _trajectory_to_cpu
+
+
+def animate_scene_gif(
+    *,
+    out_path: Path,
+    room: Sequence[float] | torch.Tensor,
+    sources: object | torch.Tensor | Sequence,
+    mics: object | torch.Tensor | Sequence,
+    src_traj: Optional[torch.Tensor | Sequence] = None,
+    mic_traj: Optional[torch.Tensor | Sequence] = None,
+    step: int = 1,
+    fps: Optional[float] = None,
+    signal_len: Optional[int] = None,
+    fs: Optional[float] = None,
+    duration_s: Optional[float] = None,
+    plot_2d: bool = True,
+    plot_3d: bool = False,
+) -> Path:
+    """Render a GIF showing source/mic trajectories.
+
+    Args:
+        out_path: Destination GIF path.
+        room: Room size tensor or sequence.
+        sources: Source positions or Source-like object.
+        mics: Microphone positions or MicrophoneArray-like object.
+        src_traj: Optional source trajectory (T, n_src, dim).
+        mic_traj: Optional mic trajectory (T, n_mic, dim).
+        step: Subsampling step for trajectories.
+        fps: Frames per second for the GIF (auto if None).
+        signal_len: Optional signal length (samples) to infer elapsed time.
+        fs: Sample rate used with signal_len.
+        duration_s: Optional total duration in seconds (overrides signal_len/fs).
+        plot_2d: Use 2D projection if True.
+        plot_3d: Use 3D projection if True and dim == 3.
+
+    Returns:
+        The output path.
+
+    Example:
+        >>> animate_scene_gif(
+        ...     out_path=Path("outputs/scene.gif"),
+        ...     room=[6.0, 4.0, 3.0],
+        ...     sources=[[1.0, 2.0, 1.5]],
+        ...     mics=[[2.0, 2.0, 1.5]],
+        ...     src_traj=src_traj,
+        ...     mic_traj=mic_traj,
+        ...     signal_len=16000,
+        ...     fs=16000,
+        ... )
+    """
+    import matplotlib.pyplot as plt
+    from matplotlib import animation
+
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    room_size = _to_cpu(room)
+    src_pos = _positions_to_cpu(sources)
+    mic_pos = _positions_to_cpu(mics)
+    dim = int(room_size.numel())
+    view_dim = 3 if (plot_3d and dim == 3) else 2
+    view_room = room_size[:view_dim]
+    view_src = src_pos[:, :view_dim]
+    view_mic = mic_pos[:, :view_dim]
+
+    if src_traj is None and mic_traj is None:
+        raise ValueError("at least one trajectory is required for animation")
+    steps = _traj_steps(src_traj, mic_traj)
+    src_traj = _trajectory_to_cpu(src_traj, src_pos, steps)
+    mic_traj = _trajectory_to_cpu(mic_traj, mic_pos, steps)
+    view_src_traj = src_traj[:, :, :view_dim]
+    view_mic_traj = mic_traj[:, :, :view_dim]
+
+    if view_dim == 3:
+        fig = plt.figure()
+        ax = fig.add_subplot(111, projection="3d")
+        ax.set_xlim(0, view_room[0].item())
+        ax.set_ylim(0, view_room[1].item())
+        ax.set_zlim(0, view_room[2].item())
+        ax.set_xlabel("x")
+        ax.set_ylabel("y")
+        ax.set_zlabel("z")
+    else:
+        fig, ax = plt.subplots()
+        ax.set_xlim(0, view_room[0].item())
+        ax.set_ylim(0, view_room[1].item())
+        ax.set_aspect("equal", adjustable="box")
+        ax.set_xlabel("x")
+        ax.set_ylabel("y")
+
+    src_scatter = ax.scatter([], [], marker="^", color="tab:green", label="sources")
+    mic_scatter = ax.scatter([], [], marker="o", color="tab:orange", label="mics")
+    src_lines = []
+    mic_lines = []
+    for _ in range(view_src_traj.shape[1]):
+        if view_dim == 2:
+            line, = ax.plot([], [], color="tab:green", alpha=0.6)
+        else:
+            line, = ax.plot([], [], [], color="tab:green", alpha=0.6)
+        src_lines.append(line)
+    for _ in range(view_mic_traj.shape[1]):
+        if view_dim == 2:
+            line, = ax.plot([], [], color="tab:orange", alpha=0.6)
+        else:
+            line, = ax.plot([], [], [], color="tab:orange", alpha=0.6)
+        mic_lines.append(line)
+
+    ax.legend(loc="best")
+
+    if duration_s is None and signal_len is not None and fs is not None:
+        duration_s = float(signal_len) / float(fs)
+
+    def _frame(i: int):
+        idx = min(i * step, view_src_traj.shape[0] - 1)
+        src_frame = view_src_traj[: idx + 1]
+        mic_frame = view_mic_traj[: idx + 1]
+        src_pos_frame = view_src_traj[idx]
+        mic_pos_frame = view_mic_traj[idx]
+
+        if view_dim == 2:
+            src_scatter.set_offsets(src_pos_frame)
+            mic_scatter.set_offsets(mic_pos_frame)
+            for s_idx, line in enumerate(src_lines):
+                xy = src_frame[:, s_idx, :]
+                line.set_data(xy[:, 0], xy[:, 1])
+            for m_idx, line in enumerate(mic_lines):
+                xy = mic_frame[:, m_idx, :]
+                line.set_data(xy[:, 0], xy[:, 1])
+        else:
+            src_scatter._offsets3d = (
+                src_pos_frame[:, 0],
+                src_pos_frame[:, 1],
+                src_pos_frame[:, 2],
+            )
+            mic_scatter._offsets3d = (
+                mic_pos_frame[:, 0],
+                mic_pos_frame[:, 1],
+                mic_pos_frame[:, 2],
+            )
+            for s_idx, line in enumerate(src_lines):
+                xyz = src_frame[:, s_idx, :]
+                line.set_data(xyz[:, 0], xyz[:, 1])
+                line.set_3d_properties(xyz[:, 2])
+            for m_idx, line in enumerate(mic_lines):
+                xyz = mic_frame[:, m_idx, :]
+                line.set_data(xyz[:, 0], xyz[:, 1])
+                line.set_3d_properties(xyz[:, 2])
+        if duration_s is not None and steps > 1:
+            t = (idx / (steps - 1)) * duration_s
+            ax.set_title(f"t = {t:.2f} s")
+        return [src_scatter, mic_scatter, *src_lines, *mic_lines]
+
+    frames = max(1, (view_src_traj.shape[0] + step - 1) // step)
+    if fps is None or fps <= 0:
+        if duration_s is not None and duration_s > 0:
+            fps = frames / duration_s
+        else:
+            fps = 6.0
+    anim = animation.FuncAnimation(fig, _frame, frames=frames, interval=1000 / fps, blit=False)
+    anim.save(out_path, writer="pillow", fps=fps)
+    plt.close(fig)
+    return out_path

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/config.py

@@ -10,7 +10,12 @@ import torch
 
 @dataclass(frozen=True)
 class SimulationConfig:
-    """Configuration values for RIR simulation and convolution."""
+    """Configuration values for RIR simulation and convolution.
+
+    Example:
+        >>> cfg = SimulationConfig(max_order=6, tmax=0.3, device="auto")
+        >>> cfg.validate()
+    """
 
     fs: Optional[float] = None
     max_order: Optional[int] = None
@@ -53,7 +58,11 @@ class SimulationConfig:
 
 
 def default_config() -> SimulationConfig:
-    """Return the default simulation configuration."""
+    """Return the default simulation configuration.
+
+    Example:
+        >>> cfg = default_config()
+    """
     cfg = SimulationConfig()
     cfg.validate()
     return cfg

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/core.py

@@ -58,6 +58,18 @@ def simulate_rir(
 
     Returns:
         Tensor of shape (n_src, n_mic, nsample).
+
+    Example:
+        >>> room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+        >>> sources = Source.positions([[1.0, 2.0, 1.5]])
+        >>> mics = MicrophoneArray.positions([[2.0, 2.0, 1.5]])
+        >>> rir = simulate_rir(
+        ...     room=room,
+        ...     sources=sources,
+        ...     mics=mics,
+        ...     max_order=6,
+        ...     tmax=0.3,
+        ... )
     """
     cfg = config or default_config()
     cfg.validate()
@@ -208,6 +220,24 @@ def simulate_dynamic_rir(
 
     Returns:
         Tensor of shape (T, n_src, n_mic, nsample).
+
+    Example:
+        >>> room = Room.shoebox(size=[6.0, 4.0, 3.0], fs=16000, beta=[0.9] * 6)
+        >>> from torchrir import linear_trajectory
+        >>> src_traj = torch.stack(
+        ...     [linear_trajectory(torch.tensor([1.0, 2.0, 1.5]),
+        ...                        torch.tensor([4.0, 2.0, 1.5]), 8)],
+        ...     dim=1,
+        ... )
+        >>> mic_pos = torch.tensor([[2.0, 2.0, 1.5]])
+        >>> mic_traj = mic_pos.unsqueeze(0).repeat(8, 1, 1)
+        >>> rirs = simulate_dynamic_rir(
+        ...     room=room,
+        ...     src_traj=src_traj,
+        ...     mic_traj=mic_traj,
+        ...     max_order=4,
+        ...     tmax=0.3,
+        ... )
     """
     cfg = config or default_config()
     cfg.validate()

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/datasets/cmu_arctic.py

@@ -49,6 +49,13 @@ class CmuArcticSentence:
 
 
 class CmuArcticDataset:
+    """CMU ARCTIC dataset loader.
+
+    Example:
+        >>> dataset = CmuArcticDataset(Path("datasets/cmu_arctic"), speaker="bdl", download=True)
+        >>> audio, fs = dataset.load_wav("arctic_a0001")
+    """
+
     def __init__(self, root: Path, speaker: str = "bdl", download: bool = False) -> None:
         """Initialize a CMU ARCTIC dataset handle.
 
@@ -182,7 +189,11 @@ def _parse_text_line(line: str) -> Tuple[str, str]:
 
 
 def load_wav_mono(path: Path) -> Tuple[torch.Tensor, int]:
-    """Load a wav file and return mono audio and sample rate."""
+    """Load a wav file and return mono audio and sample rate.
+
+    Example:
+        >>> audio, fs = load_wav_mono(Path("datasets/cmu_arctic/ARCTIC/.../wav/arctic_a0001.wav"))
+    """
     import soundfile as sf
 
     audio, sample_rate = sf.read(str(path), dtype="float32", always_2d=True)
@@ -195,7 +206,11 @@ def load_wav_mono(path: Path) -> Tuple[torch.Tensor, int]:
 
 
 def save_wav(path: Path, audio: torch.Tensor, sample_rate: int) -> None:
-    """Save a mono or multi-channel wav to disk."""
+    """Save a mono or multi-channel wav to disk.
+
+    Example:
+        >>> save_wav(Path("outputs/example.wav"), audio, sample_rate)
+    """
     import soundfile as sf
 
     audio = audio.detach().cpu().clamp(-1.0, 1.0).to(torch.float32)

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/datasets/utils.py

@@ -11,7 +11,12 @@ from .base import BaseDataset, SentenceLike
 
 
 def choose_speakers(dataset: BaseDataset, num_sources: int, rng: random.Random) -> List[str]:
-    """Select unique speakers for the requested number of sources."""
+    """Select unique speakers for the requested number of sources.
+
+    Example:
+        >>> rng = random.Random(0)
+        >>> speakers = choose_speakers(dataset, num_sources=2, rng=rng)
+    """
     speakers = dataset.list_speakers()
     if not speakers:
         raise RuntimeError("no speakers available")
@@ -27,7 +32,20 @@ def load_dataset_sources(
     duration_s: float,
     rng: random.Random,
 ) -> Tuple[torch.Tensor, int, List[Tuple[str, List[str]]]]:
-    """Load and concatenate utterances for each speaker into fixed-length signals."""
+    """Load and concatenate utterances for each speaker into fixed-length signals.
+
+    Example:
+        >>> from pathlib import Path
+        >>> from torchrir import CmuArcticDataset
+        >>> 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),
+        ...     num_sources=2,
+        ...     duration_s=10.0,
+        ...     rng=rng,
+        ... )
+    """
     dataset0 = dataset_factory(None)
     speakers = choose_speakers(dataset0, num_sources, rng)
     signals: List[torch.Tensor] = []

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/dynamic.py

@@ -17,7 +17,12 @@ from .signal import _ensure_dynamic_rirs, _ensure_signal
 
 @dataclass(frozen=True)
 class DynamicConvolver:
-    """Convolver for time-varying RIRs."""
+    """Convolver for time-varying RIRs.
+
+    Example:
+        >>> convolver = DynamicConvolver(mode="trajectory")
+        >>> y = convolver.convolve(signal, rirs)
+    """
 
     mode: str = "trajectory"
     hop: Optional[int] = None
@@ -28,7 +33,11 @@ class DynamicConvolver:
         return self.convolve(signal, rirs)
 
     def convolve(self, signal: Tensor, rirs: Tensor) -> Tensor:
-        """Convolve signals with time-varying RIRs."""
+        """Convolve signals with time-varying RIRs.
+
+        Example:
+            >>> y = DynamicConvolver(mode="hop", hop=1024).convolve(signal, rirs)
+        """
         if self.mode not in ("trajectory", "hop"):
             raise ValueError("mode must be 'trajectory' or 'hop'")
         if self.mode == "hop":

{torchrir-0.1.0 → torchrir-0.1.2}/src/torchrir/logging_utils.py

@@ -9,7 +9,12 @@ from typing import Optional
 
 @dataclass(frozen=True)
 class LoggingConfig:
-    """Configuration for torchrir logging."""
+    """Configuration for torchrir logging.
+
+    Example:
+        >>> config = LoggingConfig(level="INFO")
+        >>> logger = setup_logging(config)
+    """
 
     level: str | int = "INFO"
     format: str = "%(levelname)s:%(name)s:%(message)s"
@@ -33,7 +38,12 @@ class LoggingConfig:
 
 
 def setup_logging(config: LoggingConfig, *, name: str = "torchrir") -> logging.Logger:
-    """Configure and return the base torchrir logger."""
+    """Configure and return the base torchrir logger.
+
+    Example:
+        >>> logger = setup_logging(LoggingConfig(level="DEBUG"))
+        >>> logger.info("ready")
+    """
     logger = logging.getLogger(name)
     level = config.resolve_level()
     logger.setLevel(level)
@@ -47,7 +57,11 @@ def setup_logging(config: LoggingConfig, *, name: str = "torchrir") -> logging.L
 
 
 def get_logger(name: Optional[str] = None) -> logging.Logger:
-    """Return a torchrir logger, namespaced under the torchrir root."""
+    """Return a torchrir logger, namespaced under the torchrir root.
+
+    Example:
+        >>> logger = get_logger("examples.static")
+    """
     if not name:
         return logging.getLogger("torchrir")
     if name.startswith("torchrir"):