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
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`.
......@@ -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
~~~~~~~~~~~~~~~~~~~~~
......@@ -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
test/torchaudio_unittest/backend_test.py
View file @ fa2e4fd4
......@@ -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
torchaudio/__init__.py
View file @ fa2e4fd4
......@@ -9,7 +9,7 @@ from torchaudio import (
transforms
)
USE_SOUNDFILE_LEGACY_INTERFACE = True
USE_SOUNDFILE_LEGACY_INTERFACE = None
from torchaudio.backend import (
list_audio_backends,
......
torchaudio/backend/utils.py
View file @ fa2e4fd4
......@@ -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 '
......@@ -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:
......@@ -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:
......
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