backend.rst 2.42 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
There are currently two implementations available.
14

15
16
* :py:mod:`"sox_io" <torchaudio.backends.sox_io_backend>` (default on Linux/macOS)
* :py:mod:`"soundfile" <torchaudio.backends.soundfile_backend>` (default on Windows)
17
18

.. note::
19
   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`.
20
21
22
23

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

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

26
``"soundfile"`` backend requires ``SoundFile``. Please refer to `the SoundFile documentation <https://pysoundfile.readthedocs.io/en/latest/>`_ for the installation.
27
28
29
30

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

31
32
33
34
35
36
37
Structures used to report the metadata of audio files.

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

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

38
.. py:module:: torchaudio.backend.sox_io_backend
39

40
41
Sox IO Backend
~~~~~~~~~~~~~~
42

43
The ``sox_io`` backend is available and default on Linux/macOS and not available on Windows.
44

45
46
47
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;
48
49
50

.. code::

51
   torchaudio.set_audio_backend("sox_io")
52
53
54
55

info
----

56
.. autofunction:: torchaudio.backend.sox_io_backend.info
57
58
59
60

load
----

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

save
----

66
.. autofunction:: torchaudio.backend.sox_io_backend.save
67

68
.. py:module:: torchaudio.backend.soundfile_backend
69
70
71
72

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

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

75
You can switch from another backend to the ``"soundfile"`` backend with the following;
76
77
78

.. code::

79
   torchaudio.set_audio_backend("soundfile")
80
81

info
82
----
83

84
.. autofunction:: torchaudio.backend.soundfile_backend.info
85
86

load
Prabhat Roy's avatar
Prabhat Roy committed
87
----
88

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

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

94
.. autofunction:: torchaudio.backend.soundfile_backend.save