[doc] Update backend docstring/documentation #935

mthrok · 2020-10-02T19:19:57Z

Update documentation for backend. This includes,

Documentation for the new interface of "soundfile" backend.
The timeline for the change of default backend and deprecation of "sox" backend and "soundfile" backend with the legacy interface.
Deprecation warnings to the classes removed as part of backend removals.

docs/source/backend.rst

cpuhrsch · 2020-10-06T16:16:54Z

docs/source/backend.rst

 :mod:`torchaudio.backend` module provides implementations for audio file I/O, using different backend libraries.
 To switch backend, use :py:func:`torchaudio.set_audio_backend`. To check the current backend use :py:func:`torchaudio.get_audio_backend`.

-.. warning::
-   Although ``sox`` backend is default for backward compatibility reason, it has a number of issues, therefore it is highly recommended to use ``sox_io`` backend instead. Note, however, that due to the interface refinement, functions defined in ``sox`` backend and those defined in ``sox_io`` backend do not have the same signatures.
+There are currently four implementations available.


I'd mention which one is the default and whether users actually need to worry about this in most cases

Also write out why you might care about reading this section and give an overview of its content.

Okay, so the description here was basically duplications from description of each backend. So I removed the description here and made the list into links to the backends. That way, the list here will only give the necessary information (default/deprecated).

So the Overall section will talk about stuff things across backends.

docs/source/backend.rst

cpuhrsch · 2020-10-06T16:19:38Z

docs/source/backend.rst


-There are currently three implementations available.
+``"sox_io"`` backend is the new backend which is built on ``libsox``, and bound with ``TorchScript``. This backend requires C++ extension module and is not available on Windows system. Function calls to this backend are TorchScript-able. This backend will become the default backend in ``"0.8.0"`` release.


You use the word backend 4 times here

"and bound with TorchScript" doesn't mean much to most users I'd say. Instead write that this implies.

"This backend requires C++ extension module" - Is this something I'd need to install or worry about in most cases? Or is it only something to worry about on Windows? If I'm on Windows, what can I do? (add this to the intro). You probably want to have a platform-specific suggestion or guidance in the intro (might simply be Windows vs. not-Windows) and also again whether the user needs to worry or more specifically when the user needs to worry (e.g. mp3 support).

Bonus points for mentioning we're working on resolving some of these issues, e.g. mp3 work in progress for Windows etc., and a link to the corresponding issue

Addressed all the suggestions. I am hesitant to mention the new I/O work as it's very early phase and we do not know when it will be available.

cpuhrsch · 2020-10-06T16:22:41Z

docs/source/backend.rst

-    * :ref:`sox<sox_backend>`
-    * :ref:`sox_io<sox_io_backend>`
-    * :ref:`soundfile<soundfile_backend>`
+``"soundfile"`` backend is built on ``PySoundFile``. You need to install ``PySoundFile`` separately. The current interface of this backend (legacy interface) will be changed in ``0.8.0`` (new interface) to match the ``"sox_io"`` backend.


"You need to install PySoundFile separately." - how do I get it?

"The current interface of this backend (legacy interface) will be changed in 0.8.0 (new interface) to match the "sox_io" backend." - More detail in the corresponding issue? Which one is it?

cpuhrsch · 2020-10-06T16:23:47Z

docs/source/backend.rst


-``sox`` backend is the original backend which is built on ``libsox``. This module is currently default but is known to have number of issues, such as wrong handling of WAV files other than 16-bit signed integer. Users are encouraged to use ``sox_io`` backend. This backend requires C++ extension module and is not available on Windows system.
+.. note::
+   Instead of calling functions in :mod:`torchaudio.backend` directly, please use ``torchaudio.info``, ``torhcaudio.load``, ``torchaudio.load_wav`` and ``torchaudio.save`` with proper backend set with :func:`torchaudio.get_audio_backend`.


Ideally we'd even have a tutorial or some kind of example somewhere that illustrates this behavior.

nit: "torhcaudio" -> "torchaudio"

We probably want to redo https://pytorch.org/tutorials/beginner/audio_preprocessing_tutorial.html

docs/source/backend.rst

mruberry · 2020-10-06T18:50:09Z

docs/source/backend.rst


 .. code::

   torchaudio.set_audio_backend("sox_io")

-The function call to this backend can be Torchsript-able. You can apply :func:`torch.jit.script` and dump the object to file, then call it from C++ application.
+The function calls to this backend are TorchSript-able. You can apply :func:`torch.jit.script` and dump the object toa file, then call it from C++ application.


Probably not for this PR, but this might be a good opportunity to elaborate with an example, or point the reader to another reference.

Let me work on this as a follow up. I have a internal presentation scheduled this Thursday on this topic, so you will have a better understanding of what it will be like too.

docs/source/backend.rst

torchaudio/backend/_soundfile_backend.py

torchaudio/backend/common.py

torchaudio/backend/sox_io_backend.py

docs/source/backend.rst

torchaudio/backend/common.py

cpuhrsch · 2020-10-09T16:49:23Z

torchaudio/backend/_soundfile_backend.py

@@ -210,6 +210,10 @@ def load_wav(
 ) -> Tuple[torch.Tensor, int]:
    """Load wave file.

+    Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

cpuhrsch · 2020-10-09T16:50:51Z

torchaudio/backend/common.py

@@ -72,6 +89,10 @@ def __init__(self,

 _LOAD_DOCSTRING = r"""Loads an audio file from disk into a tensor

+Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

cpuhrsch · 2020-10-09T16:50:55Z

torchaudio/backend/common.py

@@ -124,6 +145,11 @@ def __init__(self,
 It assumes that the wav file uses 16 bit per sample that needs normalization by
 shifting the input right by 16 bits.

+Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

cpuhrsch · 2020-10-09T16:50:58Z

torchaudio/backend/common.py

@@ -135,6 +161,10 @@ def __init__(self,

 _SAVE_DOCSTRING = r"""Saves a Tensor on file as an audio file

+Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

cpuhrsch · 2020-10-09T16:51:02Z

torchaudio/backend/common.py

@@ -149,6 +179,10 @@ def __init__(self,

 _INFO_DOCSTRING = r"""Gets metadata from an audio file without loading the signal.

+Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

cpuhrsch · 2020-10-09T16:52:28Z

torchaudio/backend/sox_io_backend.py

@@ -184,6 +184,9 @@ def load_wav(
 ) -> Tuple[torch.Tensor, int]:
    """Load wave file.

+    Warnings:


I think this is unnecessary, because it's duplicated with the warning statement and because we don't do this in any other library.

vincentqb · 2020-10-09T16:55:53Z

torchaudio/backend/sox_io_backend.py

        filepath (str or pathlib.Path):
-        Path to audio file. This function also handles ``pathlib.Path`` objects, but is annotated as
-        ``str`` for TorchScript compiler compatibility.
+            Path to audio file. This function also handles ``pathlib.Path`` objects,
+            but is annotated as ``str`` for TorchScript compatibility.


looks like pathlib is the new standard, so could extend to where it also supported elsewhere

vincentqb

LGTM, let's land this :)

word_language_model/generate.py reads a model file trained with CUDA, into CPU if CUDA is not available.

mthrok requested a review from mruberry October 2, 2020 19:20

vincentqb reviewed Oct 2, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

cpuhrsch reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

cpuhrsch reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

cpuhrsch reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/_soundfile_backend.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/common.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/common.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/common.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/common.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/sox_io_backend.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/sox_io_backend.py Outdated Show resolved Hide resolved

mruberry reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/sox_io_backend.py Outdated Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Outdated Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

docs/source/backend.rst Show resolved Hide resolved

vincentqb reviewed Oct 6, 2020

View reviewed changes

torchaudio/backend/common.py Outdated Show resolved Hide resolved

mthrok added 2 commits October 6, 2020 17:08

Update backend docstring/documentation

5404163

Update the docs

b668a16

mthrok force-pushed the doc-backend branch from eb602fb to b668a16 Compare October 6, 2020 23:42

mthrok added 4 commits October 6, 2020 19:47

Fix typo

3873d5b

Added the direction

2ca5125

update

86f6824

update

1e92904

cpuhrsch reviewed Oct 9, 2020

View reviewed changes

cpuhrsch approved these changes Oct 9, 2020

View reviewed changes

vincentqb reviewed Oct 9, 2020

View reviewed changes

vincentqb approved these changes Oct 9, 2020

View reviewed changes

mthrok changed the title ~~Update backend docstring/documentation~~ [doc] Update backend docstring/documentation Oct 9, 2020

Remove warnings from docstring

10c514e

mthrok merged commit e17c263 into pytorch:master Oct 9, 2020

mthrok deleted the doc-backend branch October 9, 2020 18:05

mthrok added the dockathon label Jan 13, 2021

mpc001 pushed a commit to mpc001/audio that referenced this pull request Aug 4, 2023

Merge pull request pytorch#935 from kaiidams/kaiidams/cudacpu

58645a1

word_language_model/generate.py reads a model file trained with CUDA, into CPU if CUDA is not available.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[doc] Update backend docstring/documentation #935

[doc] Update backend docstring/documentation #935

mthrok commented Oct 2, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

mthrok Oct 6, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

mthrok Oct 7, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

cpuhrsch Oct 6, 2020

mruberry Oct 6, 2020

mthrok Oct 6, 2020

cpuhrsch Oct 9, 2020 •

edited

Loading

cpuhrsch Oct 9, 2020

cpuhrsch Oct 9, 2020

cpuhrsch Oct 9, 2020

cpuhrsch Oct 9, 2020

cpuhrsch Oct 9, 2020

vincentqb Oct 9, 2020

vincentqb left a comment


		There are currently three implementations available.
		``"sox_io"`` backend is the new backend which is built on ``libsox``, and bound with ``TorchScript``. This backend requires C++ extension module and is not available on Windows system. Function calls to this backend are TorchScript-able. This backend will become the default backend in ``"0.8.0"`` release.

		@@ -72,6 +89,10 @@ def __init__(self,

		_LOAD_DOCSTRING = r"""Loads an audio file from disk into a tensor

		Warnings:

		@@ -135,6 +161,10 @@ def __init__(self,

		_SAVE_DOCSTRING = r"""Saves a Tensor on file as an audio file

		Warnings:

		@@ -149,6 +179,10 @@ def __init__(self,

		_INFO_DOCSTRING = r"""Gets metadata from an audio file without loading the signal.

		Warnings:

[doc] Update backend docstring/documentation #935

[doc] Update backend docstring/documentation #935

Conversation

mthrok commented Oct 2, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cpuhrsch Oct 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincentqb left a comment

Choose a reason for hiding this comment

cpuhrsch Oct 9, 2020 •

edited

Loading