diff --git a/docs/source/backend.rst b/docs/source/backend.rst index 920fb36dbc..1cdb1c923e 100644 --- a/docs/source/backend.rst +++ b/docs/source/backend.rst @@ -10,14 +10,12 @@ Overview There are currently four implementations available. -* :ref:`"sox" ` (deprecated, default on Linux/macOS) -* :ref:`"sox_io" ` (default on Linux/macOS from the 0.8.0 release) -* :ref:`"soundfile" - legacy interface ` (deprecated, default on Windows) -* :ref:`"soundfile" - new interface ` (default on Windows from the 0.8.0 release) +* :ref:`"sox_io" ` (default on Linux/macOS) +* :ref:`"sox" ` (deprecated, will be removed in 0.9.0 release) +* :ref:`"soundfile" ` (default on Windows) +* :ref:`"soundfile" (legacy interface) ` (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 `_ 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 `_ 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 `_. + +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 `_. +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 `_ 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) ` 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 diff --git a/test/torchaudio_unittest/backend_test.py b/test/torchaudio_unittest/backend_test.py index 5696cf8524..3f355be0cb 100644 --- a/test/torchaudio_unittest/backend_test.py +++ b/test/torchaudio_unittest/backend_test.py @@ -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 diff --git a/torchaudio/__init__.py b/torchaudio/__init__.py index 389d91f635..ef0b0a41ea 100644 --- a/torchaudio/__init__.py +++ b/torchaudio/__init__.py @@ -9,7 +9,7 @@ transforms ) -USE_SOUNDFILE_LEGACY_INTERFACE = True +USE_SOUNDFILE_LEGACY_INTERFACE = None from torchaudio.backend import ( list_audio_backends, diff --git a/torchaudio/backend/utils.py b/torchaudio/backend/utils.py index 77575f3151..b888c04c48 100644 --- a/torchaudio/backend/utils.py +++ b/torchaudio/backend/utils.py @@ -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: