Replace torchaudio's audio I/O uses (load, save, info) with a soundfile-based compatibility wrapper

This PR successfully replaces all torchaudio.{load,save,info} calls (~228 occurrences) across the repository with a new soundfile-based compatibility layer, decoupling audio I/O from torchaudio's ML transforms while maintaining identical API behavior.

Implementation Complete ✅

• Create speechbrain/dataio/audio_io.py with soundfile-based implementations
• Add soundfile>=0.12.1 to requirements.txt
• Replace all torchaudio.load() calls (~85 occurrences)
• Replace all torchaudio.save() calls (~86 occurrences)
• Replace all torchaudio.info() calls (~57 occurrences)
• Update docstring examples in inference modules
• Add tests/unittests/test_audio_io.py
• Address PR review feedback:
  • Convert AudioInfo to dataclass
  • Add channels_first parameter to save()
  • Fix always_2d precedence over channels_first in load()
  • Change always_2d default to True (matching torchaudio)
  • Change subtype default to None (smart subtyping)
  • Add usage example at top of audio_io.py
  • Update docs/audioloading.rst to reflect soundfile backend

Changes

New module: speechbrain/dataio/audio_io.py

• load(path, *, channels_first=True, dtype=torch.float32, always_2d=True, frame_offset=0, num_frames=-1)
• save(path, src, sample_rate, channels_first=True, subtype=None) with flexible shape handling
• info(path) returns AudioInfo dataclass with sample_rate, frames, channels, subtype, format, duration
• Full compatibility with torchaudio signatures including partial file loading

Core modules updated (17 files)

• speechbrain/inference/* - All inference modules
• speechbrain/dataio/{dataio,legacy,preprocess}.py
• speechbrain/augment/preparation.py
• speechbrain/integrations/k2_fsa/align.py

Recipe files updated (89 files)

• All major datasets: LibriMix, VoxCeleb, CommonVoice, LJSpeech, Voicebank, ESC50, etc.
• Data preparation and training scripts

Documentation

• Updated docs/audioloading.rst to document soundfile as primary backend
• Added usage examples and troubleshooting information

Dependencies

• Added soundfile>=0.12.1 to requirements.txt
• Kept torchaudio dependency (still used for transforms.Resample and functional)

Testing

• Added tests/unittests/test_audio_io.py with 12 test cases covering WAV/FLAC roundtrip, metadata retrieval, partial loading, channel ordering, various shapes/dtypes

Example Usage

from speechbrain.dataio import audio_io

# Drop-in replacement for torchaudio.load/save/info
audio, sr = audio_io.load("example.wav", channels_first=True)
audio_io.save("output.wav", audio, sr)
info = audio_io.info("example.wav")  # info.sample_rate, info.frames, info.duration

# Supports partial loading (like torchaudio)
audio, sr = audio_io.load("large.wav", frame_offset=1000, num_frames=5000)

Preserved Functionality

• torchaudio.transforms.Resample (unchanged - still used throughout)
• torchaudio.functional (unchanged)
• All existing APIs and behavior maintained

This pull request was created as a result of the following prompt from Copilot chat.

Replace torchaudio's audio I/O uses (load, save, info) across the repository with a lightweight soundfile-based compatibility wrapper at speechbrain/dataio/audio_io.py.

Scope and goals:

• Add a new module at speechbrain/dataio/audio_io.py that implements a minimal compatibility layer for torchaudio I/O using the soundfile (pysoundfile) library and torch:
  • load(path, *, channels_first=True, dtype=torch.float32, always_2d=False) -> (tensor, sample_rate)
  • info(path) -> object with sample_rate, frames, channels, subtype, format, duration property
  • save(path, src, sample_rate, subtype="PCM_16") -> writes audio to disk. The signature should be simple and similar to torchaudio.save(path, src, sample_rate).
  • list_audio_backends() -> ["soundfile"] (optional but helpful)
• Use soundfile for reading/writing. Do not include ffmpeg fallbacks or an AudioEffector in this PR.
• Do NOT change or remove torchaudio dependency. Keep torchaudio.transforms.Resample and any other non-I/O torchaudio uses intact.
• Replace all call sites of torchaudio.load(), torchaudio.save(), and torchaudio.info() in the repository with calls to the new audio_io (e.g., from speechbrain.dataio import audio_io as audio_io; audio_io.load(...)). Keep the call semantics compatible: audio_io.save(path, src, sample_rate) should accept the same tensor shapes commonly used in the repo and handle batched/mono/stereo shapes gracefully.
• Update code examples (docstrings) that call torchaudio.load/save/info to call audio_io equivalents, to avoid misleading docs.
• Add soundfile to the repository's top-level requirements (requirements.txt) so CI installs it.
• Add unit tests: minimal tests to check load/save roundtrip for WAV and FLAC, and info() returns expected fields. Place tests under tests/unittests/test_audio_io.py.

Files to be added/changed (non-exhaustive; the coding agent should find and replace all occurrences programmatically):

• ADD: speechbrain/dataio/audio_io.py (new file)
• MODIFY: speechbrain/inference/enhancement.py (replace torchaudio.save(...) with audio_io.save(...))
• MODIFY: recipes/CVSS/S2ST/extract_code.py (replace torchaudio.info(...) with audio_io.info(...))
• MODIFY: speechbrain/inference/classifiers.py (docstring examples: torchaudio.load -> audio_io.load)
• MODIFY: speechbrain/inference/speaker.py (docstring examples: torchaudio.load -> audio_io.load)
• MODIFY: docs/audioloading.rst to mention soundfile as supported I/O backend for SpeechBrain I/O (optional but helpful)
• MODIFY: requirements.txt (add soundfile)
• ADD: tests/unittests/test_audio_io.py with basic roundtrip tests

Implementation details / compatibility notes:

• audio_io.load should use soundfile.read(..., dtype='float32', always_2d=True). Convert numpy arrays to torch tensors and return either channels-first (channels, frames) or (frames, channels) depending on channels_first flag. If mono, return (1, frames) when channels_first True to be consistent with torchaudio.
• audio_io.save should accept torch.Tensor or numpy arrays; detect shape and convert to (frames, channels) when writing with soundfile.write.
• audio_io.info should use soundfile.info and expose a simple dataclass-like object with sample_rate, frames, channels, subtype, format, and duration property.
• Make the implementation robust with clear error messages when files are missing or shapes are unsupported.

Tests:

• test_audio_io_roundtrip_wav: generate a small sine wave, save with audio_io.save to a temporary file, load back with audio_io.load and assert sample rate and close numeric equality within tolerance.
• test_audio_io_info: write a temporary file and assert audio_io.info returns expected sample_rate, frames and channels.

Please create a feature branch, apply the changes, run tests (if possible in CI), and open a PR with a descriptive title and checklist of changes. Include a clear PR description documenting that this is a first pass focusing only on torchaudio.load/save/info substitution and that AudioEffector and other advanced torchaudio I/O features were intentionally omitted.

Do not modify torchaudio.transforms.Resample usages. Keep torchaudio dependency in requirements.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.