• Docs >
  • torchaudio >
  • Old version (stable)
Shortcuts

torchaudio

I/O

torchaudio top-level module provides the following functions that make it easy to handle audio data.

info

Get signal information of an audio file.

load

Load audio data from source.

save

Save audio data to file.

Backend and Dispatcher

Decoding and encoding media is highly elaborated process. Therefore, TorchAudio relies on third party libraries to perform these operations. These third party libraries are called backend, and currently TorchAudio integrates the following libraries.

Please refer to Installation for how to enable backends.

Conventionally, TorchAudio has had its I/O backend set globally at runtime based on availability. However, this approach does not allow applications to use different backends, and it is not well-suited for large codebases.

For these reasons, in v2.0, we introduced a dispatcher, a new mechanism to allow users to choose a backend for each function call.

When dispatcher mode is enabled, all the I/O functions accept extra keyward argument backend, which specifies the desired backend. If the specified backend is not available, the function call will fail.

If a backend is not explicitly chosen, the functions will select a backend to use given order of precedence and library availability.

The following table summarizes the backends.

Priority

Backend

Supported OS

Note

1

FFmpeg

Linux, macOS, Windows

Use get_audio_decoders() and get_audio_encoders() to retrieve the supported codecs.

This backend Supports various protocols, such as HTTPS and MP4, and file-like objects.

2

SoX

Linux, macOS

Use list_read_formats() and list_write_formats() to retrieve the supported codecs.

This backend does not support file-like objects.

3

SoundFile

Linux, macOS, Windows

Please refer to the official document for the supported codecs.

This backend supports file-like objects.

Dispatcher Migration

We are migrating the I/O functions to use the dispatcher mechanism, and this incurs multiple changes, some of which involve backward-compatibility-breaking changes, and require users to change their function call.

The (planned) changes are as follows. For up-to-date information, please refer to https://github.com/pytorch/audio/issues/2950

  • In 2.0, audio I/O backend dispatcher was introduced. Users can opt-in to using dispatcher by setting the environment variable TORCHAUDIO_USE_BACKEND_DISPATCHER=1.

  • In 2.1, the disptcher becomes the default mechanism for I/O. Those who need to keep using the previous mechanism (global backend) can do so by setting TORCHAUDIO_USE_BACKEND_DISPATCHER=0.

  • In 2.2, the legacy global backend mechanism will be removed. Utility functions get_audio_backend() and set_audio_backend() become no-op.

Furthermore, we are removing file-like object support from libsox backend, as this is better supported by FFmpeg backend and makes the build process simpler. Therefore, beginning with 2.1, FFmpeg and Soundfile are the sole backends that support file-like objects.

Backend Utilities

The following functions are effective only when backend dispatcher is disabled.

Note that the changes in 2.1 marks get_audio_backend() and set_audio_backend() deprecated.

list_audio_backends

List available backends

get_audio_backend

DEPRECATED: Get the name of the current global backend

set_audio_backend

DEPRECATED: Set the global backend.

Docs

Access comprehensive developer documentation for PyTorch

View Docs

Tutorials

Get in-depth tutorials for beginners and advanced developers

View Tutorials

Resources

Find development resources and get your questions answered

View Resources