backend.rst 2.84 KB
Newer Older
1
2
3
4
5
.. _backend:

torchaudio.backend
==================

moto's avatar
moto committed
6
7
.. py:module:: torchaudio.backend

8
9
Overview
~~~~~~~~
10

11
:mod:`torchaudio.backend` module provides implementations for audio file I/O functionalities, which are ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save``.
12

13
14
15
16
17
.. note::
   Release 2.1 will revise ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save`` to allow for backend selection via function parameter rather than ``torchaudio.set_audio_backend``, with FFmpeg being the default backend.
   The new logic can be enabled in the current release by setting environment variable ``TORCHAUDIO_USE_BACKEND_DISPATCHER=1``.
   See :ref:`future_api` for details on the new API.

18
There are currently two implementations available.
19

20
21
* :py:mod:`"sox_io" <torchaudio.backends.sox_io_backend>` (default on Linux/macOS)
* :py:mod:`"soundfile" <torchaudio.backends.soundfile_backend>` (default on Windows)
22
23

.. note::
24
   Instead of calling functions in ``torchaudio.backend`` directly, please use ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save`` with proper backend set with :func:`torchaudio.set_audio_backend`.
25
26
27
28

Availability
------------

Prabhat Roy's avatar
Prabhat Roy committed
29
``"sox_io"`` backend requires C++ extension module, which is included in Linux/macOS binary distributions. This backend is not available on Windows.
30

31
``"soundfile"`` backend requires ``SoundFile``. Please refer to `the SoundFile documentation <https://pysoundfile.readthedocs.io/en/latest/>`_ for the installation.
32
33
34
35

Common Data Structure
~~~~~~~~~~~~~~~~~~~~~

36
37
38
39
40
41
42
Structures used to report the metadata of audio files.

AudioMetaData
-------------

.. autoclass:: torchaudio.backend.common.AudioMetaData

43
.. py:module:: torchaudio.backend.sox_io_backend
44

45
46
Sox IO Backend
~~~~~~~~~~~~~~
47

48
The ``sox_io`` backend is available and default on Linux/macOS and not available on Windows.
49

50
51
52
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;
53
54
55

.. code::

56
   torchaudio.set_audio_backend("sox_io")
57
58
59
60

info
----

61
.. autofunction:: torchaudio.backend.sox_io_backend.info
62
63
64
65

load
----

66
.. autofunction:: torchaudio.backend.sox_io_backend.load
67
68
69
70

save
----

71
.. autofunction:: torchaudio.backend.sox_io_backend.save
72

73
.. py:module:: torchaudio.backend.soundfile_backend
74
75
76
77

Soundfile Backend
~~~~~~~~~~~~~~~~~

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

80
You can switch from another backend to the ``"soundfile"`` backend with the following;
81
82
83

.. code::

84
   torchaudio.set_audio_backend("soundfile")
85
86

info
87
----
88

89
.. autofunction:: torchaudio.backend.soundfile_backend.info
90
91

load
Prabhat Roy's avatar
Prabhat Roy committed
92
----
93

94
.. autofunction:: torchaudio.backend.soundfile_backend.load
95
96

save
Prabhat Roy's avatar
Prabhat Roy committed
97
----
98

99
.. autofunction:: torchaudio.backend.soundfile_backend.save