Skip to content

GitLab

Unverified Commit fa2e4fd4 authored by moto's avatar moto Committed by GitHub
Browse files

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

Refer to #903 for the overview of planned I/O changes.

* Change the default backend from `"sox"(deprecated)` to `"sox_io"`
* Change the default interface of `"soundfile"` backend to the one identical to `"sox_io"` backend.
* Deprecate torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE
* Update documentations
    * Re-order backends (default first)
    * Update overhaul timeline (removed 0.7.0)
    * Simplify `"soundfile"` backend description
parent b34bc7d3
Hide whitespace changes
Inline Side-by-side
Showing with 90 additions and 113 deletions
docs/source/backend.rst
View file @ fa2e4fd4
...@@ -10,14 +10,12 @@ Overview ...@@ -10,14 +10,12 @@ Overview
There are currently four implementations available. 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)
* :ref:`"sox_io" <sox_io_backend>` (default on Linux/macOS from the 0.8.0 release) * :ref:`"sox" <sox_backend>` (deprecated, will be removed in 0.9.0 release)
* :ref:`"soundfile" - legacy interface <soundfile_legacy_backend>` (deprecated, default on Windows) * :ref:`"soundfile" <soundfile_backend>` (default on Windows)
* :ref:`"soundfile" - new interface <soundfile_backend>` (default on Windows from the 0.8.0 release) * :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. 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.
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.
.. note:: .. 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`. 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`.
...@@ -32,27 +30,24 @@ Availability ...@@ -32,27 +30,24 @@ Availability
Changes in default backend and deprecation 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 module is going through a major overhaul. The following table summarizes the timeline for the deprecations and removals.
+--------------------+--------------------------+-----------------------+------------------------+ +--------------------+-----------------------+------------------------+
| **Backend** | **0.7.0** | **0.8.0** | **0.9.0** | | **Backend** | **0.8.0** | **0.9.0** |
+====================+==========================+=======================+========================+ +====================+=======================+========================+
| ``"sox"`` | Default on Linux/macOS | Available | Removed | | ``"sox_io"`` | Default on Linx/macOS | Default on Linux/macOS |
| (deprecated) | | | | +--------------------+-----------------------+------------------------+
+--------------------+--------------------------+-----------------------+------------------------+ | ``"sox"`` | Available | Removed |
| ``"sox_io"`` | Available | Default on Linx/macOS | Default on Linux/macOS | | (deprecated) | | |
+--------------------+--------------------------+-----------------------+------------------------+ +--------------------+-----------------------+------------------------+
| ``"soundfile"`` | Default on Windows | Available | Removed | | ``"soundfile"`` | Default on Windows | Default on Windows |
| (legacy interface, | | | | +--------------------+-----------------------+------------------------+
| deprecated) | | | | | ``"soundfile"`` | Available | Removed |
+--------------------+--------------------------+-----------------------+------------------------+ | (legacy interface, | | |
| ``"soundfile"`` | Available | Default on Windows | Default on Windows | | deprecated) | | |
| (new interface) | | | | +--------------------+-----------------------+------------------------+
+--------------------+--------------------------+-----------------------+------------------------+
* The ``"sox"`` and ``"soundfile" (legacy interface)`` backends are deprecated and will be removed in 0.9.0 release.
* 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.
Common Data Structure Common Data Structure
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
...@@ -74,158 +69,139 @@ EncodingInfo (Deprecated) ...@@ -74,158 +69,139 @@ EncodingInfo (Deprecated)
.. autoclass:: torchaudio.backend.common.EncodingInfo .. 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:: .. code::
torchaudio.set_audio_backend("sox") torchaudio.set_audio_backend("sox_io")
info info
---- ----
.. autofunction:: torchaudio.backend.sox_backend.info .. autofunction:: torchaudio.backend.sox_io_backend.info
load 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 save
---- ----
.. autofunction:: torchaudio.backend.sox_backend.save .. autofunction:: torchaudio.backend.sox_io_backend.save
others
------
.. automodule:: torchaudio.backend.sox_backend
:members:
:exclude-members: info, load, load_wav, save
.. _sox_io_backend:
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:: .. code::
torchaudio.set_audio_backend("sox_io") torchaudio.set_audio_backend("sox")
info info
---- ----
.. autofunction:: torchaudio.backend.sox_io_backend.info .. autofunction:: torchaudio.backend.sox_backend.info
load 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 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 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 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. You can switch from another backend to the ``"soundfile"`` backend with the following;
* 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.
.. code:: .. code::
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True torchaudio.set_audio_backend("soundfile")
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.
To switch to this backend/interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend. .. note::
If you are switching from `"soundfile" (legacy interface) <soundfile_legacy_backend>` backend, 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
info info
^^^^ ^^^^
.. autofunction:: torchaudio.backend.soundfile_backend.info .. autofunction:: torchaudio.backend._soundfile_backend.info
load 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 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. To switch to this backend/interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
.. code:: .. code::
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio.set_audio_backend("soundfile") # The new interface torchaudio.set_audio_backend("soundfile") # The legacy interface
info info
^^^^ ^^^^
.. autofunction:: torchaudio.backend._soundfile_backend.info .. autofunction:: torchaudio.backend.soundfile_backend.info
load 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 save
^^^^ ^^^^
.. autofunction:: torchaudio.backend._soundfile_backend.save .. autofunction:: torchaudio.backend.soundfile_backend.save
test/torchaudio_unittest/backend_test.py
View file @ fa2e4fd4
...@@ -42,14 +42,14 @@ class TestBackendSwitch_soundfile_legacy(BackendSwitchMixin, common_utils.Torcha ...@@ -42,14 +42,14 @@ class TestBackendSwitch_soundfile_legacy(BackendSwitchMixin, common_utils.Torcha
backend = 'soundfile' backend = 'soundfile'
backend_module = torchaudio.backend.soundfile_backend 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') @common_utils.skipIfNoModule('soundfile')
class TestBackendSwitch_soundfile(BackendSwitchMixin, common_utils.TorchaudioTestCase): class TestBackendSwitch_soundfile(BackendSwitchMixin, common_utils.TorchaudioTestCase):
backend = 'soundfile' backend = 'soundfile'
backend_module = torchaudio.backend._soundfile_backend backend_module = torchaudio.backend._soundfile_backend
def setUp(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False
def tearDown(self):
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
torchaudio/__init__.py
View file @ fa2e4fd4
...@@ -9,7 +9,7 @@ from torchaudio import ( ...@@ -9,7 +9,7 @@ from torchaudio import (
transforms transforms
) )
USE_SOUNDFILE_LEGACY_INTERFACE = True USE_SOUNDFILE_LEGACY_INTERFACE = None
from torchaudio.backend import ( from torchaudio.backend import (
list_audio_backends, list_audio_backends,
......
torchaudio/backend/utils.py
View file @ fa2e4fd4
...@@ -42,6 +42,12 @@ def set_audio_backend(backend: Optional[str]): ...@@ -42,6 +42,12 @@ def set_audio_backend(backend: Optional[str]):
One of ``"sox"``, ``"sox_io"`` or ``"soundfile"`` based on availability One of ``"sox"``, ``"sox_io"`` or ``"soundfile"`` based on availability
of the system. If ``None`` is provided the current backend is unassigned. 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(): if backend is not None and backend not in list_audio_backends():
raise RuntimeError( raise RuntimeError(
f'Backend "{backend}" is not one of ' f'Backend "{backend}" is not one of '
...@@ -51,22 +57,17 @@ def set_audio_backend(backend: Optional[str]): ...@@ -51,22 +57,17 @@ def set_audio_backend(backend: Optional[str]):
module = no_backend module = no_backend
elif backend == 'sox': elif backend == 'sox':
warnings.warn( warnings.warn(
'"sox" backend is being deprecated. ' '"sox" backend is depredated and will be removed in 0.9.0. '
'The default backend will be changed to "sox_io" backend in 0.8.0 and ' 'Please use "sox_io" backend.'
'"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.')
module = sox_backend module = sox_backend
elif backend == 'sox_io': elif backend == 'sox_io':
module = sox_io_backend module = sox_io_backend
elif backend == 'soundfile': elif backend == 'soundfile':
if torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE: if torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE:
warnings.warn( warnings.warn(
'The interface of "soundfile" backend is planned to change in 0.8.0 to ' 'The legacy interface of "soundfile" backend is depredated and will be removed in 0.9.0. '
'match that of "sox_io" backend and the current interface will be removed in 0.9.0. ' 'Please migrate to the new interface.'
'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.'
) )
module = soundfile_backend module = soundfile_backend
else: else:
...@@ -81,7 +82,7 @@ def set_audio_backend(backend: Optional[str]): ...@@ -81,7 +82,7 @@ def set_audio_backend(backend: Optional[str]):
def _init_audio_backend(): def _init_audio_backend():
backends = list_audio_backends() backends = list_audio_backends()
if 'sox' in backends: if 'sox' in backends:
set_audio_backend('sox') set_audio_backend('sox_io')
elif 'soundfile' in backends: elif 'soundfile' in backends:
set_audio_backend('soundfile') set_audio_backend('soundfile')
else: else:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment