Skip to content

Commit 68614e8

Browse files
mthrokmthrok
committed
Update docs
* Re-order backends (default first) * Update timeline * Simplify soundfile backend description
1 parent 7f8768b commit 68614e8

File tree

1 file changed

+71
-95
lines changed

1 file changed

+71
-95
lines changed

‎docs/source/backend.rst‎

Lines changed: 71 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,12 @@ Overview
1010

1111
There are currently four implementations available.
1212

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

18-
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.
19-
20-
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.
18+
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.
2119

2220
.. note::
2321
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
3230
Changes in default backend and deprecation
3331
------------------------------------------
3432

35-
Backend module is going through a major overhaul. The following table summarizes the timeline for the changes and deprecations.
36-
37-
+--------------------+--------------------------+-----------------------+------------------------+
38-
| **Backend** | **0.7.0** | **0.8.0** | **0.9.0** |
39-
+====================+==========================+=======================+========================+
40-
| ``"sox"`` | Default on Linux/macOS | Available | Removed |
41-
| (deprecated) | | | |
42-
+--------------------+--------------------------+-----------------------+------------------------+
43-
| ``"sox_io"`` | Available | Default on Linx/macOS | Default on Linux/macOS |
44-
+--------------------+--------------------------+-----------------------+------------------------+
45-
| ``"soundfile"`` | Default on Windows | Available | Removed |
46-
| (legacy interface, | | | |
47-
| deprecated) | | | |
48-
+--------------------+--------------------------+-----------------------+------------------------+
49-
| ``"soundfile"`` | Available | Default on Windows | Default on Windows |
50-
| (new interface) | | | |
51-
+--------------------+--------------------------+-----------------------+------------------------+
52-
53-
* The default backend for Linux/macOS will be changed from ``"sox"`` to ``"sox_io"`` in ``0.8.0`` release.
54-
* The ``"sox"`` backend will be removed in the ``0.9.0`` release.
55-
* 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.
33+
Backend module is going through a major overhaul. The following table summarizes the timeline for the deprecations and removals.
34+
35+
+--------------------+-----------------------+------------------------+
36+
| **Backend** | **0.8.0** | **0.9.0** |
37+
+====================+=======================+========================+
38+
| ``"sox_io"`` | Default on Linx/macOS | Default on Linux/macOS |
39+
+--------------------+-----------------------+------------------------+
40+
| ``"sox"`` | Available | Removed |
41+
| (deprecated) | | |
42+
+--------------------+-----------------------+------------------------+
43+
| ``"soundfile"`` | Default on Windows | Default on Windows |
44+
+--------------------+-----------------------+------------------------+
45+
| ``"soundfile"`` | Available | Removed |
46+
| (legacy interface, | | |
47+
| deprecated) | | |
48+
+--------------------+-----------------------+------------------------+
49+
50+
* The ``"sox"`` and ``"soundfile" (legacy interface)`` backends are deprecated and will be removed in 0.9.0 release.
5651

5752
Common Data Structure
5853
~~~~~~~~~~~~~~~~~~~~~
@@ -74,158 +69,139 @@ EncodingInfo (Deprecated)
7469

7570
.. autoclass:: torchaudio.backend.common.EncodingInfo
7671

77-
.. _sox_backend:
72+
.. _sox_io_backend:
7873

79-
Sox Backend (Deprecated)
80-
~~~~~~~~~~~~~~~~~~~~~~~~
74+
Sox IO Backend
75+
~~~~~~~~~~~~~~
8176

82-
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.
77+
The ``"sox_io"`` backend is available and default on Linux/macOS and not available on Windows.
8378

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

8683
.. code::
8784
88-
torchaudio.set_audio_backend("sox")
85+
torchaudio.set_audio_backend("sox_io")
8986
9087
info
9188
----
9289

93-
.. autofunction:: torchaudio.backend.sox_backend.info
90+
.. autofunction:: torchaudio.backend.sox_io_backend.info
9491

9592
load
9693
----
9794

98-
.. autofunction:: torchaudio.backend.sox_backend.load
95+
.. autofunction:: torchaudio.backend.sox_io_backend.load
9996

100-
.. autofunction:: torchaudio.backend.sox_backend.load_wav
97+
.. autofunction:: torchaudio.backend.sox_io_backend.load_wav
10198

10299

103100
save
104101
----
105102

106-
.. autofunction:: torchaudio.backend.sox_backend.save
107-
108-
others
109-
------
110-
111-
.. automodule:: torchaudio.backend.sox_backend
112-
:members:
113-
:exclude-members: info, load, load_wav, save
114-
115-
.. _sox_io_backend:
103+
.. autofunction:: torchaudio.backend.sox_io_backend.save
116104

117-
Sox IO Backend
118-
~~~~~~~~~~~~~~
105+
.. _sox_backend:
119106

120-
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.
107+
Sox Backend (Deprecated)
108+
~~~~~~~~~~~~~~~~~~~~~~~~
121109

122-
I/O functions of this backend support `TorchScript <https://pytorch.org/docs/stable/jit.html>`_.
110+
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.
123111

124-
You can switch from another backend to the ``sox_io`` backend with the following;
112+
You can switch from another backend to ``sox`` backend with the following;
125113

126114
.. code::
127115
128-
torchaudio.set_audio_backend("sox_io")
116+
torchaudio.set_audio_backend("sox")
129117
130118
info
131119
----
132120

133-
.. autofunction:: torchaudio.backend.sox_io_backend.info
121+
.. autofunction:: torchaudio.backend.sox_backend.info
134122

135123
load
136124
----
137125

138-
.. autofunction:: torchaudio.backend.sox_io_backend.load
126+
.. autofunction:: torchaudio.backend.sox_backend.load
139127

140-
.. autofunction:: torchaudio.backend.sox_io_backend.load_wav
128+
.. autofunction:: torchaudio.backend.sox_backend.load_wav
141129

142130

143131
save
144132
----
145133

146-
.. autofunction:: torchaudio.backend.sox_io_backend.save
134+
.. autofunction:: torchaudio.backend.sox_backend.save
147135

148-
.. _soundfile_legacy_backend:
136+
others
137+
------
138+
139+
.. automodule:: torchaudio.backend.sox_backend
140+
:members:
141+
:exclude-members: info, load, load_wav, save
142+
143+
.. _soundfile_backend:
149144

150145
Soundfile Backend
151146
~~~~~~~~~~~~~~~~~
152147

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

155-
The ``"soundfile"`` backend has two interfaces, legacy and new.
156-
157-
* In the ``0.7.0`` release, the legacy interface is used by default when switching to the ``"soundfile"`` backend.
158-
* In the ``0.8.0`` release, the new interface will become the default.
159-
* In the ``0.9.0`` release, the legacy interface will be removed.
160-
161-
To change the interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
150+
You can switch from another backend to the ``"soundfile"`` backend with the following;
162151

163152
.. code::
164153
165-
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
166-
torchaudio.set_audio_backend("soundfile") # The legacy interface
167-
168-
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False
169-
torchaudio.set_audio_backend("soundfile") # The new interface
170-
171-
Legacy Interface (Deprecated)
172-
-----------------------------
173-
174-
``"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.
154+
torchaudio.set_audio_backend("soundfile")
175155
176-
To switch to this backend/interface, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
177-
178-
.. code::
179-
180-
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
181-
torchaudio.set_audio_backend("soundfile") # The legacy interface
156+
.. note::
157+
If you are switching from `"soundfile" (legacy interface) <soundfile_legacy_backend>` backend, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
182158

183159
info
184160
^^^^
185161

186-
.. autofunction:: torchaudio.backend.soundfile_backend.info
162+
.. autofunction:: torchaudio.backend._soundfile_backend.info
187163

188164
load
189165
^^^^
190166

191-
.. autofunction:: torchaudio.backend.soundfile_backend.load
167+
.. autofunction:: torchaudio.backend._soundfile_backend.load
192168

193-
.. autofunction:: torchaudio.backend.soundfile_backend.load_wav
169+
.. autofunction:: torchaudio.backend._soundfile_backend.load_wav
194170

195171

196172
save
197173
^^^^
198174

199-
.. autofunction:: torchaudio.backend.soundfile_backend.save
175+
.. autofunction:: torchaudio.backend._soundfile_backend.save
200176

201-
.. _soundfile_backend:
177+
.. _soundfile_legacy_backend:
202178

203-
New Interface
204-
-------------
179+
Legacy Interface (Deprecated)
180+
-----------------------------
205181

206-
The ``"soundfile"`` backend with new interface will become the default in the ``0.8.0`` release.
182+
``"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.
207183

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

210186
.. code::
211187
212-
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = False
213-
torchaudio.set_audio_backend("soundfile") # The new interface
188+
torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE = True
189+
torchaudio.set_audio_backend("soundfile") # The legacy interface
214190
215191
info
216192
^^^^
217193

218-
.. autofunction:: torchaudio.backend._soundfile_backend.info
194+
.. autofunction:: torchaudio.backend.soundfile_backend.info
219195

220196
load
221197
^^^^
222198

223-
.. autofunction:: torchaudio.backend._soundfile_backend.load
199+
.. autofunction:: torchaudio.backend.soundfile_backend.load
224200

225-
.. autofunction:: torchaudio.backend._soundfile_backend.load_wav
201+
.. autofunction:: torchaudio.backend.soundfile_backend.load_wav
226202

227203

228204
save
229205
^^^^
230206

231-
.. autofunction:: torchaudio.backend._soundfile_backend.save
207+
.. autofunction:: torchaudio.backend.soundfile_backend.save

0 commit comments

Comments
 (0)