Skip to content

Switch the default backend to the ones with new interfaces #978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 27, 2020
Merged

Switch the default backend to the ones with new interfaces #978

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7f8768b
Switch default backends
mthrok Oct 21, 2020
68614e8
Update docs
mthrok Oct 21, 2020
826b994
Deprecate torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE
mthrok Oct 26, 2020
609d19e
Tweak test to reduce wranings
mthrok Oct 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 71 additions & 95 deletions docs/source/backend.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,12 @@ Overview

There are currently four implementations available.

* :ref:`"sox" <sox_backend>` (deprecated, default on Linux/macOS)
* :ref:`"sox_io" <sox_io_backend>` (default on Linux/macOS from the 0.8.0 release)
* :ref:`"soundfile" - legacy interface <soundfile_legacy_backend>` (deprecated, default on Windows)
* :ref:`"soundfile" - new interface <soundfile_backend>` (default on Windows from the 0.8.0 release)
* :ref:`"sox_io" <sox_io_backend>` (default on Linux/macOS)
* :ref:`"sox" <sox_backend>` (deprecated, will be removed in 0.9.0 release)
* :ref:`"soundfile" <soundfile_backend>` (default on Windows)
* :ref:`"soundfile" (legacy interface) <soundfile_legacy_backend>` (deprecated, will be removed in 0.9.0 release)

On Windows, only the ``"soundfile"`` backend (with both interfaces) are available. It is recommended to use the new interface as the legacy interface is deprecated.

On Linux/macOS, please use ``"sox_io"`` backend. The use of ``"sox"`` backend is strongly discouraged as it cannot correctly handle formats other than 16-bit integer WAV. See `#726 <https://github.com/pytorch/audio/pull/726>`_ for the detail.
The use of ``"sox"`` backend is strongly discouraged as it cannot correctly handle formats other than 16-bit integer WAV. See `#726 <https://github.com/pytorch/audio/pull/726>`_ for the detail.

.. note::
Instead of calling functions in ``torchaudio.backend`` directly, please use ``torchaudio.info``, ``torchaudio.load``, ``torchaudio.load_wav`` and ``torchaudio.save`` with proper backend set with :func:`torchaudio.set_audio_backend`.
Expand All @@ -32,27 +30,24 @@ Availability
Changes in default backend and deprecation
------------------------------------------

Backend module is going through a major overhaul. The following table summarizes the timeline for the changes and deprecations.

+--------------------+--------------------------+-----------------------+------------------------+
| **Backend** | **0.7.0** | **0.8.0** | **0.9.0** |
+====================+==========================+=======================+========================+
| ``"sox"`` | Default on Linux/macOS | Available | Removed |
| (deprecated) | | | |
+--------------------+--------------------------+-----------------------+------------------------+
| ``"sox_io"`` | Available | Default on Linx/macOS | Default on Linux/macOS |
+--------------------+--------------------------+-----------------------+------------------------+
| ``"soundfile"`` | Default on Windows | Available | Removed |
| (legacy interface, | | | |
| deprecated) | | | |
+--------------------+--------------------------+-----------------------+------------------------+
| ``"soundfile"`` | Available | Default on Windows | Default on Windows |
| (new interface) | | | |
+--------------------+--------------------------+-----------------------+------------------------+

* The default backend for Linux/macOS will be changed from ``"sox"`` to ``"sox_io"`` in ``0.8.0`` release.
* The ``"sox"`` backend will be removed in the ``0.9.0`` release.
* Starting from the 0.8.0 release, ``"soundfile"`` backend will use the new interface, which has the same interface as ``"sox_io"`` backend. The legacy interface will be removed in the ``0.9.0`` release.
Backend module is going through a major overhaul. The following table summarizes the timeline for the deprecations and removals.

+--------------------+-----------------------+------------------------+
| **Backend** | **0.8.0** | **0.9.0** |
+====================+=======================+========================+
| ``"sox_io"`` | Default on Linx/macOS | Default on Linux/macOS |
+--------------------+-----------------------+------------------------+
| ``"sox"`` | Available | Removed |
| (deprecated) | | |
+--------------------+-----------------------+------------------------+
| ``"soundfile"`` | Default on Windows | Default on Windows |
+--------------------+-----------------------+------------------------+
| ``"soundfile"`` | Available | Removed |
| (legacy interface, | | |
| deprecated) | | |
+--------------------+-----------------------+------------------------+

* The ``"sox"`` and ``"soundfile" (legacy interface)`` backends are deprecated and will be removed in 0.9.0 release.

Common Data Structure
~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -74,158 +69,139 @@ EncodingInfo (Deprecated)

.. autoclass:: torchaudio.backend.common.EncodingInfo

.. _sox_backend:
.. _sox_io_backend:

Sox Backend (Deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~
Sox IO Backend
~~~~~~~~~~~~~~

The ``"sox"`` backend is available on Linux/macOS and not available on Windows. This backend is currently the default when available, but is deprecated and will be removed in ``0.9.0`` release.
The ``"sox_io"`` backend is available and default on Linux/macOS and not available on Windows.

You can switch from another backend to ``sox`` backend with the following;
I/O functions of this backend support `TorchScript <https://pytorch.org/docs/stable/jit.html>`_.

You can switch from another backend to the ``sox_io`` backend with the following;

.. code::

torchaudio.set_audio_backend("sox")
torchaudio.set_audio_backend("sox_io")

info
----

.. autofunction:: torchaudio.backend.sox_backend.info
.. autofunction:: torchaudio.backend.sox_io_backend.info

load
----

.. autofunction:: torchaudio.backend.sox_backend.load
.. autofunction:: torchaudio.backend.sox_io_backend.load

.. autofunction:: torchaudio.backend.sox_backend.load_wav
.. autofunction:: torchaudio.backend.sox_io_backend.load_wav


save
----

.. autofunction:: torchaudio.backend.sox_backend.save

others
------

.. automodule:: torchaudio.backend.sox_backend
:members:
:exclude-members: info, load, load_wav, save

.. _sox_io_backend:
.. autofunction:: torchaudio.backend.sox_io_backend.save

Sox IO Backend
~~~~~~~~~~~~~~
.. _sox_backend:

The ``"sox_io"`` backend is available on Linux/macOS and not available on Windows. This backend is recommended over the ``"sox"`` backend, and will become the default in the ``0.8.0`` release.
Sox Backend (Deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~

I/O functions of this backend support `TorchScript <https://pytorch.org/docs/stable/jit.html>`_.
The ``"sox"`` backend is available on Linux/macOS and not available on Windows. This backend is deprecated and will be removed in ``0.9.0`` release.

You can switch from another backend to the ``sox_io`` backend with the following;
You can switch from another backend to ``sox`` backend with the following;

.. code::

torchaudio.set_audio_backend("sox_io")
torchaudio.set_audio_backend("sox")

info
----

.. autofunction:: torchaudio.backend.sox_io_backend.info
.. autofunction:: torchaudio.backend.sox_backend.info

load
----

.. autofunction:: torchaudio.backend.sox_io_backend.load
.. autofunction:: torchaudio.backend.sox_backend.load

.. autofunction:: torchaudio.backend.sox_io_backend.load_wav
.. autofunction:: torchaudio.backend.sox_backend.load_wav


save
----

.. autofunction:: torchaudio.backend.sox_io_backend.save
.. autofunction:: torchaudio.backend.sox_backend.save

.. _soundfile_legacy_backend:
others
------

.. automodule:: torchaudio.backend.sox_backend
:members:
:exclude-members: info, load, load_wav, save

.. _soundfile_backend:

Soundfile Backend
~~~~~~~~~~~~~~~~~

The ``"soundfile"`` backend is available when `SoundFile <https://pysoundfile.readthedocs.io/en/latest/>`_ is installed. This backend is the default on Windows.

The ``"soundfile"`` backend has two interfaces, legacy and new.

* In the ``0.7.0`` release, the legacy interface is used by default when switching to the ``"soundfile"`` backend.
* In the ``0.8.0`` release, the new interface will become the default.
* In the ``0.9.0`` release, the legacy interface will be removed.

To change the interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
You can switch from another backend to the ``"soundfile"`` backend with the following;

.. code::

torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio.set_audio_backend("soundfile") # The legacy interface

torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False
torchaudio.set_audio_backend("soundfile") # The new interface

Legacy Interface (Deprecated)
-----------------------------

``"soundfile"`` backend with legacy interface is currently the default on Windows, however this interface is deprecated and will be removed in the ``0.9.0`` release.
torchaudio.set_audio_backend("soundfile")

To switch to this backend/interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.

.. code::

torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio.set_audio_backend("soundfile") # The legacy interface
.. note::
If you are switching from `"soundfile" (legacy interface) <soundfile_legacy_backend>` backend, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.

info
^^^^

.. autofunction:: torchaudio.backend.soundfile_backend.info
.. autofunction:: torchaudio.backend._soundfile_backend.info

load
^^^^

.. autofunction:: torchaudio.backend.soundfile_backend.load
.. autofunction:: torchaudio.backend._soundfile_backend.load

.. autofunction:: torchaudio.backend.soundfile_backend.load_wav
.. autofunction:: torchaudio.backend._soundfile_backend.load_wav


save
^^^^

.. autofunction:: torchaudio.backend.soundfile_backend.save
.. autofunction:: torchaudio.backend._soundfile_backend.save

.. _soundfile_backend:
.. _soundfile_legacy_backend:

New Interface
-------------
Legacy Interface (Deprecated)
-----------------------------

The ``"soundfile"`` backend with new interface will become the default in the ``0.8.0`` release.
``"soundfile"`` backend with legacy interface is made available for backward compatibility reason, however this interface is deprecated and will be removed in the ``0.9.0`` release.

To switch to this backend/interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.

.. code::

torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False
torchaudio.set_audio_backend("soundfile") # The new interface
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio.set_audio_backend("soundfile") # The legacy interface

info
^^^^

.. autofunction:: torchaudio.backend._soundfile_backend.info
.. autofunction:: torchaudio.backend.soundfile_backend.info

load
^^^^

.. autofunction:: torchaudio.backend._soundfile_backend.load
.. autofunction:: torchaudio.backend.soundfile_backend.load

.. autofunction:: torchaudio.backend._soundfile_backend.load_wav
.. autofunction:: torchaudio.backend.soundfile_backend.load_wav


save
^^^^

.. autofunction:: torchaudio.backend._soundfile_backend.save
.. autofunction:: torchaudio.backend.soundfile_backend.save
12 changes: 6 additions & 6 deletions test/torchaudio_unittest/backend_test.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,14 @@ class TestBackendSwitch_soundfile_legacy(BackendSwitchMixin, common_utils.Torcha
backend = 'soundfile'
backend_module = torchaudio.backend.soundfile_backend

def setUp(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True

def tearDown(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = None


@common_utils.skipIfNoModule('soundfile')
class TestBackendSwitch_soundfile(BackendSwitchMixin, common_utils.TorchaudioTestCase):
backend = 'soundfile'
backend_module = torchaudio.backend._soundfile_backend

def setUp(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False

def tearDown(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
2 changes: 1 addition & 1 deletion torchaudio/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
transforms
)

USE_SOUNDFILE_LEGACY_INTERFACE = True
USE_SOUNDFILE_LEGACY_INTERFACE = None

from torchaudio.backend import (
list_audio_backends,
Expand Down
23 changes: 12 additions & 11 deletions torchaudio/backend/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@ def set_audio_backend(backend: Optional[str]):
One of ``"sox"``, ``"sox_io"`` or ``"soundfile"`` based on availability
of the system. If ``None`` is provided the current backend is unassigned.
"""
if torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE is not None:
warnings.warn(
'"torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE" flag is depredated and will be removed in 0.9.0. '
'Please remove the use of flag.'
)

if backend is not None and backend not in list_audio_backends():
raise RuntimeError(
f'Backend "{backend}" is not one of '
Expand All @@ -51,22 +57,17 @@ def set_audio_backend(backend: Optional[str]):
module = no_backend
elif backend == 'sox':
warnings.warn(
'"sox" backend is being deprecated. '
'The default backend will be changed to "sox_io" backend in 0.8.0 and '
'"sox" backend will be removed in 0.9.0. Please migrate to "sox_io" backend. '
'Please refer to https://github.com/pytorch/audio/issues/903 for the detail.')
'"sox" backend is depredated and will be removed in 0.9.0. '
'Please use "sox_io" backend.'
)
module = sox_backend
elif backend == 'sox_io':
module = sox_io_backend
elif backend == 'soundfile':
if torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE:
warnings.warn(
'The interface of "soundfile" backend is planned to change in 0.8.0 to '
'match that of "sox_io" backend and the current interface will be removed in 0.9.0. '
'To use the new interface, do '
'`torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False` '
'before setting the backend to "soundfile". '
'Please refer to https://github.com/pytorch/audio/issues/903 for the detail.'
'The legacy interface of "soundfile" backend is depredated and will be removed in 0.9.0. '
'Please migrate to the new interface.'
)
module = soundfile_backend
else:
Expand All @@ -81,7 +82,7 @@ def set_audio_backend(backend: Optional[str]):
def _init_audio_backend():
backends = list_audio_backends()
if 'sox' in backends:
set_audio_backend('sox')
set_audio_backend('sox_io')
elif 'soundfile' in backends:
set_audio_backend('soundfile')
else:
Expand Down