Skip to content

GitLab

"...text-generation-inference.git" did not exist on "b3b7ea0d74627d30a0b739c5e7e4a74b4f2f4437"
Commit c0f25f21 authored by moto's avatar moto Committed by Facebook GitHub Bot
Browse files

Update I/O and backend docs (#3555) 

Summary:
* Merge backend doc into torchaudio toplevel doc
* Update backend, dispatcher, installation doc

Pull Request resolved: https://github.com/pytorch/audio/pull/3555

Reviewed By: huangruizhe

Differential Revision: D48326812

Pulled By: mthrok

fbshipit-source-id: cc0d7326eacfebd341323b5d613ca1777255748b
parent 9d8f76d9
Hide whitespace changes
Inline Side-by-side
Showing with 240 additions and 319 deletions
docs/source/_templates/autosummary/io.rst 0 → 100644
View file @ c0f25f21
..
autogenerated from source/_templates/autosummary/io.rst
{{ fullname | underline }}
.. autofunction:: {{ fullname }}
{%- if name == "info" %}
Support Structure
-----------------
AudioMetaData
~~~~~~~~~~~~~
.. autoclass:: torchaudio.AudioMetaData
{%- endif %}
docs/source/backend.rst deleted 100644 → 0
View file @ 9d8f76d9
.. _backend:
torchaudio.backend
==================
.. py:module:: torchaudio.backend
Overview
~~~~~~~~
:mod:`torchaudio.backend` module provides implementations for audio file I/O functionalities, which are ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save``.
.. 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.
There are currently two implementations available.
* :py:mod:`"sox_io" <torchaudio.backends.sox_io_backend>` (default on Linux/macOS)
* :py:mod:`"soundfile" <torchaudio.backends.soundfile_backend>` (default on Windows)
.. note::
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`.
Availability
------------
``"sox_io"`` backend requires C++ extension module, which is included in Linux/macOS binary distributions. This backend is not available on Windows.
``"soundfile"`` backend requires ``SoundFile``. Please refer to `the SoundFile documentation <https://pysoundfile.readthedocs.io/en/latest/>`_ for the installation.
Common Data Structure
~~~~~~~~~~~~~~~~~~~~~
Structures used to report the metadata of audio files.
AudioMetaData
-------------
.. autoclass:: torchaudio.AudioMetaData
.. py:module:: torchaudio.backend.sox_io_backend
Sox IO Backend
~~~~~~~~~~~~~~
The ``sox_io`` backend is available and default on Linux/macOS and not available on Windows.
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;
.. code::
torchaudio.set_audio_backend("sox_io")
info
----
.. autofunction:: torchaudio.backend.sox_io_backend.info
load
----
.. autofunction:: torchaudio.backend.sox_io_backend.load
save
----
.. autofunction:: torchaudio.backend.sox_io_backend.save
.. py:module:: torchaudio.backend.soundfile_backend
Soundfile Backend
~~~~~~~~~~~~~~~~~
The ``"soundfile"`` backend is available when `SoundFile <https://pysoundfile.readthedocs.io/en/latest/>`_ is installed. This backend is the default on Windows.
You can switch from another backend to the ``"soundfile"`` backend with the following;
.. code::
torchaudio.set_audio_backend("soundfile")
info
----
.. autofunction:: torchaudio.backend.soundfile_backend.info
load
----
.. autofunction:: torchaudio.backend.soundfile_backend.load
save
----
.. autofunction:: torchaudio.backend.soundfile_backend.save
docs/source/index.rst
View file @ c0f25f21
......@@ -97,7 +97,6 @@ model implementations and application components.
torchaudio
io
backend
functional
transforms
datasets
......
docs/source/installation.rst
View file @ c0f25f21
......@@ -31,28 +31,58 @@ Optional Dependencies
* `FFmpeg <https://ffmpeg.org>`__
Required to use :py:mod:`torchaudio.io` module. and ``backend="ffmpeg"`` in
I/O functions. (:py:func:`torchaudio.info`, :py:func:`torchaudio.load`,
:py:func:`torchaudio.save`).
`I/O functions <./torchaudio.html#i-o>`__.
TorchAudio official binary distributions are compatible with FFmpeg 4 to 6.
Starting version 2.1, TorchAudio official binary distributions are compatible with
FFmpeg version 6, 5 and 4. At runtime, TorchAudio first looks for FFmpeg 6,
if not found, then it continues to looks for 5 and move on to 4.
TorchAudio searches FFmpeg 6, 5 then 4. You can use the environment variable
``TORCHAUDIO_USE_FFMPEG_VERSION`` to specify the version you would like to use.
For example, ``TORCHAUDIO_USE_FFMPEG_VERSION=5``, will only search for FFmpeg 5.
If you need to specify the version of FFmpeg TorchAudio searches and links, you can
specify it via the environment variable ``TORCHAUDIO_USE_FFMPEG_VERSION``. For example,
by setting ``TORCHAUDIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg
5.
If dynamic linking is causing an issue, you can set the environment variable
``TORCHAUDIO_USE_FFMPEG=0``, and TorchAudio won't use FFmpeg.
If for some reason, this search mechanism is causing an issue, you can disable
the FFmpeg integration entirely by setting the environment variable
``TORCHAUDIO_USE_FFMPEG=0``.
.. note::
When searching for FFmpeg installation, TorchAudio looks for library files
which have names with version numbers.
That is, ``libavutil.so.<VERSION>`` for Linux, ``libavutil.<VERSION>.dylib``
for macOS, and ``avutil-<VERSION>.dll`` for Windows.
Many public pre-built binaries follow this naming scheme, but some distributions
have un-versioned file names.
If you are having difficulties detecting FFmpeg, double check that the library
files you installed follow this naming scheme, (and then make sure
that they are in one of the directories listed in library search path.)
* `SoX <https://sox.sourceforge.net/>`__
Required to use ``backend="sox"`` in I/O functions. (:py:func:`torchaudio.info`,
:py:func:`torchaudio.load`, :py:func:`torchaudio.save`).
Required to use ``backend="sox"`` in `I/O functions <./torchaudio.html#i-o>`__.
TorchAudio is tested on libsox 14.4.2. Other versions are not supported.
Starting version 2.1, TorchAudio requires separately installed libsox.
If dynamic linking is causing an issue, you can set the environment variable
``TORCHAUDIO_USE_SOX=0``, and TorchAudio won't use SoX.
.. note::
TorchAudio looks for a library file with unversioned name, that is ``libsox.so``
for Linux, and ``libsox.dylib`` for macOS. Some package managers install the library
file with different name. For example, aptitude on Ubuntu installs ``libsox.so.3``.
To have TorchAudio link against it, you can create a symbolic link to it with name
``libsox.so`` (and put the symlink in a library search path).
.. note::
TorchAudio is tested on libsox 14.4.2. (And it is unlikely that other
versions would work.)
* `SoundFile <https://pysoundfile.readthedocs.io/>`__
Required to use ``backend="soundfile"`` in `I/O functions <./torchaudio.html#i-o>`__.
* `sentencepiece <https://pypi.org/project/sentencepiece/>`__
Required for performing automatic speech recognition with :ref:`Emformer RNN-T<RNNT>`.
......
docs/source/torchaudio.rst
View file @ c0f25f21
torchaudio
==========
.. currentmodule:: torchaudio
I/O
---
``torchaudio`` top-level module provides the following functions that make
it easy to handle audio data.
- :py:func:`torchaudio.info`
- :py:func:`torchaudio.load`
- :py:func:`torchaudio.save`
Under the hood, these functions are implemented using various decoding/encoding
libraries. There are currently three variants.
- ``FFmpeg``
- ``libsox``
- ``SoundFile``
``libsox`` backend is the first backend implemented in TorchAudio, and it
works on Linux and macOS.
``SoundFile`` backend was added to extend audio I/O support to Windows.
It also works on Linux and macOS.
``FFmpeg`` backend is the latest addition and it supports wide range of audio, video
formats and protocols.
It works on Linux, macOS and Windows.
.. _dispatcher_migration:
Introduction of Dispatcher
~~~~~~~~~~~~~~~~~~~~~~~~~~
Conventionally, torchaudio has had its IO backend set globally at runtime based on availability.
However, this approach does not allow applications to use different
backends, and it is not well-suited for large codebases.
.. autosummary::
:toctree: generated
:nosignatures:
:template: autosummary/io.rst
For these reasons, we are introducing a dispatcher, a new mechanism to allow users to
choose a backend for each function call, and migrating the I/O functions.
This incurs multiple changes, some of which involve backward-compatibility-breaking changes, and require
users to change their function call.
The (planned) changes are as follows. For up-to-date information,
please refer to https://github.com/pytorch/audio/issues/2950
info
load
save
* In 2.0, audio I/O backend dispatcher was introduced.
Users can opt-in to using dispatcher by setting the environment variable
``TORCHAUDIO_USE_BACKEND_DISPATCHER=1``
* In 2.1, the disptcher becomes the default mechanism for I/O.
Those who need to keep using the previous mechanism (global backend) can do
so by setting ``TORCHAUDIO_USE_BACKEND_DISPATCHER=0``.
.. _backend:
Furthermore, we are removing file-like object support from libsox backend, as this
is better supported by FFmpeg backend and makes the build process simpler.
Therefore, beginning with 2.1, FFmpeg and Soundfile are the sole backends that support file-like objects.
Backend and Dispatcher
----------------------
The changes in 2.1 will mark the :ref:`backend utilities <backend_utils>` deprecated.
Decoding and encoding media is highly elaborated process. Therefore, TorchAudio
relies on third party libraries to perform these operations. These third party
libraries are called ``backend``, and currently TorchAudio integrates the
following libraries.
Current API
-----------
Please refer to `Installation <./installation.html>`__ for how to enable backends.
I/O functionalities
~~~~~~~~~~~~~~~~~~~
Conventionally, TorchAudio has had its I/O backend set globally at runtime
based on availability. However, this approach does not allow applications to
use different backends, and it is not well-suited for large codebases.
Audio I/O functions are implemented in :ref:`torchaudio.backend<backend>` module, but for the ease of use, the following functions are made available on :mod:`torchaudio` module. There are different backends available and you can switch backends with :func:`set_audio_backend`.
For these reasons, in v2.0, we introduced a dispatcher, a new mechanism to allow
users to choose a backend for each function call.
When dispatcher mode is enabled, all the I/O functions accept extra keyward argument
``backend``, which specifies the desired backend. If the specified
backend is not available, the function call will fail.
Please refer to :ref:`backend` for the detail, and the :doc:`Audio I/O tutorial <../tutorials/audio_io_tutorial>` for the usage.
If a backend is not explicitly chosen, the functions will select a backend to use given order of precedence and library availability.
The following table summarizes the backends.
torchaudio.info
~~~~~~~~~~~~~~~
.. list-table::
:header-rows: 1
:widths: 8 12 25 60
.. function:: torchaudio.info(filepath: str, ...)
* - Priority
- Backend
- Supported OS
- Note
* - 1
- FFmpeg
- Linux, macOS, Windows
- Use :py:func:`~torchaudio.utils.ffmpeg_utils.get_audio_decoders` and
:py:func:`~torchaudio.utils.ffmpeg_utils.get_audio_encoders`
to retrieve the supported codecs.
Fetch meta data of an audio file. Refer to :ref:`backend` for the detail.
This backend Supports various protocols, such as HTTPS and MP4, and file-like objects.
* - 2
- SoX
- Linux, macOS
- Use :py:func:`~torchaudio.utils.sox_utils.list_read_formats` and
:py:func:`~torchaudio.utils.sox_utils.list_write_formats`
to retrieve the supported codecs.
torchaudio.load
~~~~~~~~~~~~~~~
This backend does *not* support file-like objects.
* - 3
- SoundFile
- Linux, macOS, Windows
- Please refer to `the official document <https://pysoundfile.readthedocs.io/>`__ for the supported codecs.
.. function:: torchaudio.load(filepath: str, ...)
This backend supports file-like objects.
Load audio file into torch.Tensor object. Refer to :ref:`backend` for the detail.
.. _dispatcher_migration:
torchaudio.save
~~~~~~~~~~~~~~~
Dispatcher Migration
~~~~~~~~~~~~~~~~~~~~
.. function:: torchaudio.save(filepath: str, src: torch.Tensor, sample_rate: int, ...)
We are migrating the I/O functions to use the dispatcher mechanism, and this
incurs multiple changes, some of which involve backward-compatibility-breaking
changes, and require users to change their function call.
Save torch.Tensor object into an audio format. Refer to :ref:`backend` for the detail.
The (planned) changes are as follows. For up-to-date information,
please refer to https://github.com/pytorch/audio/issues/2950
.. currentmodule:: torchaudio
* In 2.0, audio I/O backend dispatcher was introduced.
Users can opt-in to using dispatcher by setting the environment variable
``TORCHAUDIO_USE_BACKEND_DISPATCHER=1``.
* In 2.1, the disptcher becomes the default mechanism for I/O.
Those who need to keep using the previous mechanism (global backend) can do
so by setting ``TORCHAUDIO_USE_BACKEND_DISPATCHER=0``.
* In 2.2, the legacy global backend mechanism will be removed.
Utility functions :py:func:`get_audio_backend` and :py:func:`set_audio_backend`
become no-op.
.. _backend_utils:
Furthermore, we are removing file-like object support from libsox backend, as this
is better supported by FFmpeg backend and makes the build process simpler.
Therefore, beginning with 2.1, FFmpeg and Soundfile are the sole backends that support
file-like objects.
Backend Utilities
~~~~~~~~~~~~~~~~~
-----------------
The following functions are effective only when backend dispatcher is disabled.
They are effectively deprecated.
.. autofunction:: list_audio_backends
.. autofunction:: get_audio_backend
.. autofunction:: set_audio_backend
.. _future_api:
Future API
----------
Dispatcher
~~~~~~~~~~
The dispatcher tries to use the I/O backend in the following order of precedence
1. FFmpeg
2. libsox
3. soundfile
One can pass ``backend`` argument to I/O functions to override this.
See :ref:`future_api` for details on the new API.
In the next release, each of ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save`` will allow for selecting a backend to use via parameter ``backend``.
The functions will support using any of FFmpeg, SoX, and SoundFile, provided that the corresponding library is installed.
If a backend is not explicitly chosen, the functions will select a backend to use given order of precedence (FFmpeg, SoX, SoundFile) and library availability.
Note that only FFmpeg and SoundFile will support file-like objects.
These functions can be enabled in the current release by setting environment variable ``TORCHAUDIO_USE_BACKEND_DISPATCHER=1``.
.. currentmodule:: torchaudio._backend
torchaudio.info
~~~~~~~~~~~~~~~
.. autofunction:: info
:noindex:
torchaudio.load
~~~~~~~~~~~~~~~
.. autofunction:: load
:noindex:
Note that the changes in 2.1 marks :py:func:`get_audio_backend` and
:py:func:`set_audio_backend` deprecated.
torchaudio.save
~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated
:nosignatures:
.. autofunction:: save
:noindex:
list_audio_backends
get_audio_backend
set_audio_backend
torchaudio/_backend/__init__.py
View file @ c0f25f21
import warnings
from typing import List, Optional
import torchaudio
from torchaudio._internal.module_utils import deprecated
from . import utils
......@@ -14,15 +14,42 @@ def _init_backend():
def list_audio_backends() -> List[str]:
"""List available backends
Returns:
list of str: The list of available backends.
The possible values are;
- Dispatcher mode: ``"ffmpeg"``, ``"sox"`` and ``"soundfile"``.
- Legacy backend mode: ``"sox_io"``, ``"soundfile"``.
"""
return list(utils.get_available_backends().keys())
# Temporary until global backend is removed
@deprecated("With dispatcher enabled, this function is no-op. You can remove the function call.")
def get_audio_backend() -> Optional[str]:
warnings.warn("I/O Dispatcher is enabled. There is no global audio backend.", stacklevel=2)
"""Get the name of the current global backend
Returns:
str or None:
If dispatcher mode is enabled, returns ``None`` otherwise,
the name of current backend or ``None`` (no backend is set).
"""
return None
# Temporary until global backend is removed
def set_audio_backend(_: Optional[str]):
warnings.warn("I/O Dispatcher is enabled. set_audio_backend is a no-op", stacklevel=2)
@deprecated("With dispatcher enabled, this function is no-op. You can remove the function call.")
def set_audio_backend(backend: Optional[str]): # noqa
"""Set the global backend.
This is a no-op when dispatcher mode is enabled.
Args:
backend (str or None): Name of the backend.
One of ``"sox_io"`` or ``"soundfile"`` based on availability
of the system. If ``None`` is provided the current backend is unassigned.
"""
pass
torchaudio/_backend/utils.py
View file @ c0f25f21
......@@ -58,19 +58,19 @@ def get_info_func():
) -> AudioMetaData:
"""Get signal information of an audio file.
Note:
When the input type is file-like object, this function cannot
get the correct length (``num_samples``) for certain formats,
such as ``vorbis``.
In this case, the value of ``num_samples`` is ``0``.
Args:
uri (path-like object or file-like object):
Source of audio data. The following types are accepted:
* ``path-like``: file path
* ``file-like``: Object with ``read(size: int) -> bytes`` method,
which returns byte string of at most ``size`` length.
Note:
When the input type is file-like object, this function cannot
get the correct length (``num_samples``) for certain formats,
such as ``vorbis``.
In this case, the value of ``num_samples`` is ``0``.
* ``path-like``: File path or URL.
* ``file-like``: Object with ``read(size: int) -> bytes`` method,
which returns byte string of at most ``size`` length.
format (str or None, optional):
If not ``None``, interpreted as hint that may allow backend to override the detected format.
......@@ -80,12 +80,17 @@ def get_info_func():
Size of buffer to use when processing file-like objects, in bytes. (Default: ``4096``)
backend (str or None, optional):
I/O backend to use. If ``None``, function selects backend given input and available backends.
Otherwise, must be one of ["ffmpeg", "sox", "soundfile"], with the corresponding backend available.
I/O backend to use.
If ``None``, function selects backend given input and available backends.
Otherwise, must be one of [``"ffmpeg"``, ``"sox"``, ``"soundfile"``],
with the corresponding backend available.
(Default: ``None``)
.. seealso::
:ref:`backend`
Returns:
AudioMetaData: Metadata of the given audio.
AudioMetaData
"""
backend = dispatcher(uri, format, backend)
return backend.info(uri, format, buffer_size)
......@@ -117,27 +122,19 @@ def get_load_func():
buffer_size: int = 4096,
backend: Optional[str] = None,
) -> Tuple[torch.Tensor, int]:
"""Load audio data from file.
Note:
The formats this function can handle depend on backend availability.
This function is tested on the following formats:
* WAV
* 32-bit floating-point
* 32-bit signed integer
* 24-bit signed integer
* 16-bit signed integer
* 8-bit unsigned integer
* FLAC
* OGG/VORBIS
* SPHERE
"""Load audio data from source.
By default (``normalize=True``, ``channels_first=True``), this function returns Tensor with
``float32`` dtype, and the shape of `[channel, time]`.
Note:
The formats this function can handle depend on the availability of backends.
Please use the following functions to fetch the supported formats.
- FFmpeg: :py:func:`torchaudio.utils.ffmpeg_utils.get_audio_decoders`
- Sox: :py:func:`torchaudio.utils.sox_utils.list_read_formats`
- SoundFile: Refer to `the official document <https://pysoundfile.readthedocs.io/>`__.
.. warning::
``normalize`` argument does not perform volume normalization.
......@@ -187,9 +184,13 @@ def get_load_func():
Size of buffer to use when processing file-like objects, in bytes. (Default: ``4096``)
backend (str or None, optional):
I/O backend to use. If ``None``, function selects backend given input and available backends.
Otherwise, must be one of ["ffmpeg", "sox", "soundfile"], with the corresponding
backend being available. (Default: ``None``)
I/O backend to use.
If ``None``, function selects backend given input and available backends.
Otherwise, must be one of [``"ffmpeg"``, ``"sox"``, ``"soundfile"``],
with the corresponding backend being available. (Default: ``None``)
.. seealso::
:ref:`backend`
Returns:
(torch.Tensor, int): Resulting Tensor and sample rate.
......@@ -232,17 +233,11 @@ def get_save_func():
Note:
The formats this function can handle depend on the availability of backends.
This function is tested on the following formats:
* WAV
Please use the following functions to fetch the supported formats.
* 32-bit floating-point
* 32-bit signed integer
* 16-bit signed integer
* 8-bit unsigned integer
* FLAC
* OGG/VORBIS
- FFmpeg: :py:func:`torchaudio.utils.ffmpeg_utils.get_audio_encoders`
- Sox: :py:func:`torchaudio.utils.sox_utils.list_write_formats`
- SoundFile: Refer to `the official document <https://pysoundfile.readthedocs.io/>`__.
Args:
uri (str or pathlib.Path): Path to audio file.
......@@ -263,11 +258,11 @@ def get_save_func():
This argument is effective only for supported formats, i.e.
``"wav"`` and ``""flac"```. Valid values are
- ``"PCM_S"`` (signed integer Linear PCM)
- ``"PCM_U"`` (unsigned integer Linear PCM)
- ``"PCM_F"`` (floating point PCM)
- ``"ULAW"`` (mu-law)
- ``"ALAW"`` (a-law)
- ``"PCM_S"`` (signed integer Linear PCM)
- ``"PCM_U"`` (unsigned integer Linear PCM)
- ``"PCM_F"`` (floating point PCM)
- ``"ULAW"`` (mu-law)
- ``"ALAW"`` (a-law)
bits_per_sample (int or None, optional): Changes the bit depth for the
supported formats.
......@@ -279,33 +274,14 @@ def get_save_func():
Size of buffer to use when processing file-like objects, in bytes. (Default: ``4096``)
backend (str or None, optional):
I/O backend to use. If ``None``, function selects backend given input and available backends.
Otherwise, must be one of ["ffmpeg", "sox", "soundfile"], with the corresponding
backend being available. (Default: ``None``)
Supported formats/encodings/bit depth/compression are:
``"wav"``
- 32-bit floating-point PCM
- 32-bit signed integer PCM
- 24-bit signed integer PCM
- 16-bit signed integer PCM
- 8-bit unsigned integer PCM
- 8-bit mu-law
- 8-bit a-law
Note:
Default encoding/bit depth is determined by the dtype of
the input Tensor.
``"flac"``
- 16-bit (default)
- 24-bit
I/O backend to use.
If ``None``, function selects backend given input and available backends.
Otherwise, must be one of [``"ffmpeg"``, ``"sox"``, ``"soundfile"``],
with the corresponding backend being available.
(Default: ``None``)
``"ogg"``
- Doesn't accept changing configuration.
.. seealso::
:ref:`backend`
"""
backend = dispatcher(uri, format, backend)
return backend.save(uri, src, sample_rate, channels_first, format, encoding, bits_per_sample, buffer_size)
......
torchaudio/_internal/module_utils.py
View file @ c0f25f21
......@@ -78,6 +78,18 @@ def deprecated(direction: str, version: Optional[str] = None, remove: bool = Fal
warnings.warn(message, stacklevel=2)
return func(*args, **kwargs)
message = "This function has been deprecated. "
if remove:
message += f'It will be removed from {"future" if version is None else version} release. '
wrapped.__doc__ = f"""DEPRECATED: {func.__doc__}
.. warning::
{message}
{direction}
"""
return wrapped
return decorator
......
torchaudio/functional/functional.py
View file @ c0f25f21
......@@ -1296,7 +1296,7 @@ def spectral_centroid(
@torchaudio._extension.fail_if_no_sox
@deprecated("Please migrate to torchaudio.io.AudioEffector.", remove=False)
@deprecated("Please migrate to :py:class:`torchaudio.io.AudioEffector`.", remove=False)
def apply_codec(
waveform: Tensor,
sample_rate: int,
......@@ -1311,12 +1311,6 @@ def apply_codec(
.. devices:: CPU
.. warning::
This function has been deprecated.
Please migrate to :py:class:`torchaudio.io.AudioEffector`, which works on all platforms,
and supports streaming processing.
Args:
waveform (Tensor): Audio data. Must be 2 dimensional. See also ```channels_first```.
sample_rate (int): Sample rate of the audio waveform.
......
torchaudio/io/_effector.py
View file @ c0f25f21
......@@ -146,9 +146,7 @@ class AudioEffector:
pad_end (bool, optional): When enabled, and if the waveform becomes shorter after applying
effects/codec, then pad the end with silence.
Examples:
* Basic usage
Example - Basic usage
To use ``AudioEffector``, first instantiate it with a set of
``effect`` and ``format``.
......@@ -165,8 +163,7 @@ class AudioEffector:
>>> for chunk in effector.stream(waveform, sample_rate):
>>> ...
* Applying effects
Example - Applying effects
Please refer to
https://ffmpeg.org/ffmpeg-filters.html#Filtergraph-description
for the overview of filter description, and
......@@ -197,8 +194,7 @@ class AudioEffector:
>>> AudioEffector(effect="")
* Applying codec
Example - Applying codec
One can apply codec using ``format`` argument. ``format`` can be
audio format or container format. If the container format supports
multiple encoders, you can specify it with ``encoder`` argument.
......@@ -225,8 +221,7 @@ class AudioEffector:
>>> AudioEffector(format="webm", encoder="opus")
* Applying codec with configuration
Example - Applying codec with configuration
Reference: https://trac.ffmpeg.org/wiki/Encode/MP3
MP3 with default config
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment