torchaudio 2.9.1__cp311-cp311-manylinux_2_28_aarch64.whl

torchaudio/__init__.py

@@ -0,0 +1,204 @@
+import os
+from typing import BinaryIO, Optional, Tuple, Union
+
+import torch
+
+# Initialize extension and backend first
+from . import _extension  # noqa  # usort: skip
+from . import compliance, datasets, functional, models, pipelines, transforms, utils  # noqa: F401
+from ._torchcodec import load_with_torchcodec, save_with_torchcodec
+
+
+try:
+    from .version import __version__, git_version  # noqa: F401
+except ImportError:
+    pass
+
+
+def load(
+    uri: Union[BinaryIO, str, os.PathLike],
+    frame_offset: int = 0,
+    num_frames: int = -1,
+    normalize: bool = True,
+    channels_first: bool = True,
+    format: Optional[str] = None,
+    buffer_size: int = 4096,
+    backend: Optional[str] = None,
+) -> Tuple[torch.Tensor, int]:
+    """Load audio data from source using TorchCodec's AudioDecoder.
+
+    .. note::
+
+        As of TorchAudio 2.9, this function relies on TorchCodec's decoding capabilities under the hood. It is
+        provided for convenience, but we do recommend that you port your code to
+        natively use ``torchcodec``'s ``AudioDecoder`` class for better
+        performance:
+        https://docs.pytorch.org/torchcodec/stable/generated/torchcodec.decoders.AudioDecoder.
+        Because of the reliance on Torchcodec, the parameters ``normalize``, ``buffer_size``, and
+        ``backend`` are ignored and accepted only for backwards compatibility.
+        To install torchcodec, follow the instructions at https://github.com/pytorch/torchcodec#installing-torchcodec.
+
+
+    Args:
+        uri (path-like object or file-like object):
+            Source of audio data. The following types are accepted:
+
+            * ``path-like``: File path or URL.
+            * ``file-like``: Object with ``read(size: int) -> bytes`` method.
+
+        frame_offset (int, optional):
+            Number of samples to skip before start reading data.
+        num_frames (int, optional):
+            Maximum number of samples to read. ``-1`` reads all the remaining samples,
+            starting from ``frame_offset``.
+        normalize (bool, optional):
+            TorchCodec always returns normalized float32 samples. This parameter
+            is ignored and a warning is issued if set to False.
+            Default: ``True``.
+        channels_first (bool, optional):
+            When True, the returned Tensor has dimension `[channel, time]`.
+            Otherwise, the returned Tensor's dimension is `[time, channel]`.
+        format (str or None, optional):
+            Format hint for the decoder. May not be supported by all TorchCodec
+            decoders. (Default: ``None``)
+        buffer_size (int, optional):
+            Not used by TorchCodec AudioDecoder. Provided for API compatibility.
+        backend (str or None, optional):
+            Not used by TorchCodec AudioDecoder. Provided for API compatibility.
+
+    Returns:
+        (torch.Tensor, int): Resulting Tensor and sample rate.
+        Always returns float32 tensors. If ``channels_first=True``, shape is
+        `[channel, time]`, otherwise `[time, channel]`.
+
+    Raises:
+        ImportError: If torchcodec is not available.
+        ValueError: If unsupported parameters are used.
+        RuntimeError: If TorchCodec fails to decode the audio.
+
+    Note:
+        - TorchCodec always returns normalized float32 samples, so the ``normalize``
+        parameter has no effect.
+        - The ``buffer_size`` and ``backend`` parameters are ignored.
+        - Not all audio formats supported by torchaudio backends may be supported
+        by TorchCodec.
+    """
+    return load_with_torchcodec(
+        uri,
+        frame_offset=frame_offset,
+        num_frames=num_frames,
+        normalize=normalize,
+        channels_first=channels_first,
+        format=format,
+        buffer_size=buffer_size,
+        backend=backend,
+    )
+
+
+def save(
+    uri: Union[str, os.PathLike],
+    src: torch.Tensor,
+    sample_rate: int,
+    channels_first: bool = True,
+    format: Optional[str] = None,
+    encoding: Optional[str] = None,
+    bits_per_sample: Optional[int] = None,
+    buffer_size: int = 4096,
+    backend: Optional[str] = None,
+    compression: Optional[Union[float, int]] = None,
+) -> None:
+    """Save audio data to file using TorchCodec's AudioEncoder.
+
+    .. note::
+
+        As of TorchAudio 2.9, this function relies on TorchCodec's encoding capabilities under the hood.
+        It is provided for convenience, but we do recommend that you port your code to
+        natively use ``torchcodec``'s ``AudioEncoder`` class for better
+        performance:
+        https://docs.pytorch.org/torchcodec/stable/generated/torchcodec.encoders.AudioEncoder.
+        Because of the reliance on Torchcodec, the parameters ``format``, ``encoding``,
+        ``bits_per_sample``, ``buffer_size``, and ``backend``, are ignored and accepted only for
+        backwards compatibility.
+        To install torchcodec, follow the instructions at https://github.com/pytorch/torchcodec#installing-torchcodec.
+
+    Args:
+        uri (path-like object):
+            Path to save the audio file. The file extension determines the format.
+
+        src (torch.Tensor):
+            Audio data to save. Must be a 1D or 2D tensor with float32 values
+            in the range [-1, 1]. If 2D, shape should be [channel, time] when
+            channels_first=True, or [time, channel] when channels_first=False.
+
+        sample_rate (int):
+            Sample rate of the audio data.
+
+        channels_first (bool, optional):
+            Indicates whether the input tensor has channels as the first dimension.
+            If True, expects [channel, time]. If False, expects [time, channel].
+            Default: True.
+
+        format (str or None, optional):
+            Audio format hint. Not used by TorchCodec (format is determined by
+            file extension). A warning is issued if provided.
+            Default: None.
+
+        encoding (str or None, optional):
+            Audio encoding. Not fully supported by TorchCodec AudioEncoder.
+            A warning is issued if provided. Default: None.
+
+        bits_per_sample (int or None, optional):
+            Bits per sample. Not directly supported by TorchCodec AudioEncoder.
+            A warning is issued if provided. Default: None.
+
+        buffer_size (int, optional):
+            Not used by TorchCodec AudioEncoder. Provided for API compatibility.
+            A warning is issued if not default value. Default: 4096.
+
+        backend (str or None, optional):
+            Not used by TorchCodec AudioEncoder. Provided for API compatibility.
+            A warning is issued if provided. Default: None.
+
+        compression (float, int or None, optional):
+            Compression level or bit rate. Maps to bit_rate parameter in
+            TorchCodec AudioEncoder. Default: None.
+
+    Raises:
+        ImportError: If torchcodec is not available.
+        ValueError: If input parameters are invalid.
+        RuntimeError: If TorchCodec fails to encode the audio.
+
+    Note:
+        - TorchCodec AudioEncoder expects float32 samples in [-1, 1] range.
+        - Some parameters (format, encoding, bits_per_sample, buffer_size, backend)
+        are not used by TorchCodec but are provided for API compatibility.
+        - The output format is determined by the file extension in the uri.
+        - TorchCodec uses FFmpeg under the hood for encoding.
+    """
+    return save_with_torchcodec(
+        uri,
+        src,
+        sample_rate,
+        channels_first=channels_first,
+        format=format,
+        encoding=encoding,
+        bits_per_sample=bits_per_sample,
+        buffer_size=buffer_size,
+        backend=backend,
+        compression=compression,
+    )
+
+
+__all__ = [
+    "load",
+    "load_with_torchcodec",
+    "save_with_torchcodec",
+    "save",
+    "compliance",
+    "datasets",
+    "functional",
+    "models",
+    "pipelines",
+    "utils",
+    "transforms",
+]

torchaudio/_extension/__init__.py

@@ -0,0 +1,61 @@
+import logging
+import os
+import sys
+
+from torchaudio._internal.module_utils import fail_with_message, is_module_available, no_op
+
+from .utils import _check_cuda_version, _init_dll_path, _load_lib
+
+_LG = logging.getLogger(__name__)
+
+
+# Note:
+# `_check_cuda_version` is not meant to be used by regular users.
+# Builder uses it for debugging purpose, so we export it.
+# https://github.com/pytorch/builder/blob/e2e4542b8eb0bdf491214451a1a4128bd606cce2/test/smoke_test/smoke_test.py#L80
+__all__ = [
+    "_check_cuda_version",
+    "_IS_TORCHAUDIO_EXT_AVAILABLE",
+    "_IS_RIR_AVAILABLE",
+]
+
+
+if os.name == "nt" and (3, 8) <= sys.version_info < (3, 9):
+    _init_dll_path()
+
+
+# When the extension module is built, we initialize it.
+# In case of an error, we do not catch the failure as it suggests there is something
+# wrong with the installation.
+_IS_TORCHAUDIO_EXT_AVAILABLE = is_module_available("torchaudio.lib._torchaudio")
+# RIR features are implemented in _torchaudio extension, but they can be individually
+# turned on/off at build time. Available means that _torchaudio is loaded properly, and
+# RIR features are found there.
+_IS_RIR_AVAILABLE = False
+_IS_ALIGN_AVAILABLE = False
+if _IS_TORCHAUDIO_EXT_AVAILABLE:
+    _load_lib("libtorchaudio")
+
+    import torchaudio.lib._torchaudio  # noqa
+
+    _check_cuda_version()
+    _IS_RIR_AVAILABLE = torchaudio.lib._torchaudio.is_rir_available()
+    _IS_ALIGN_AVAILABLE = torchaudio.lib._torchaudio.is_align_available()
+
+
+fail_if_no_rir = (
+    no_op
+    if _IS_RIR_AVAILABLE
+    else fail_with_message(
+        "requires RIR extension, but TorchAudio is not compiled with it. Please build TorchAudio with RIR support."
+    )
+)
+
+fail_if_no_align = (
+    no_op
+    if _IS_ALIGN_AVAILABLE
+    else fail_with_message(
+        "Requires alignment extension, but TorchAudio is not compiled with it. \
+        Please build TorchAudio with alignment support."
+    )
+)

torchaudio/_extension/utils.py

@@ -0,0 +1,133 @@
+"""Module to implement logics used for initializing extensions.
+
+The implementations here should be stateless.
+They should not depend on external state.
+Anything that depends on external state should happen in __init__.py
+"""
+import logging
+import os
+import types
+from pathlib import Path
+
+import torch
+
+_LG = logging.getLogger(__name__)
+_LIB_DIR = Path(__file__).parent.parent / "lib"
+
+
+def _get_lib_path(lib: str):
+    suffix = "pyd" if os.name == "nt" else "so"
+    path = _LIB_DIR / f"{lib}.{suffix}"
+    return path
+
+
+def _load_lib(lib: str) -> bool:
+    """Load extension module
+
+    Note:
+        In case `torchaudio` is deployed with `pex` format, the library file
+        is not in a standard location.
+        In this case, we expect that `libtorchaudio` is available somewhere
+        in the search path of dynamic loading mechanism, so that importing
+        `_torchaudio` will have library loader find and load `libtorchaudio`.
+        This is the reason why the function should not raising an error when the library
+        file is not found.
+
+    Returns:
+        bool:
+            True if the library file is found AND the library loaded without failure.
+            False if the library file is not found (like in the case where torchaudio
+            is deployed with pex format, thus the shared library file is
+            in a non-standard location.).
+            If the library file is found but there is an issue loading the library,
+            (such as missing dependency) then this function raises the exception as-is.
+
+    Raises:
+        Exception:
+            If the library file is found, but there is an issue loading the library file,
+            (when underlying `ctype.DLL` throws an exception), this function will pass
+            the exception as-is, instead of catching it and returning bool.
+            The expected case is `OSError` thrown by `ctype.DLL` when a dynamic dependency
+            is not found.
+            This behavior was chosen because the expected failure case is not recoverable.
+            If a dependency is missing, then users have to install it.
+    """
+    path = _get_lib_path(lib)
+    if not path.exists():
+        return False
+    torch.ops.load_library(path)
+    return True
+
+
+class _LazyImporter(types.ModuleType):
+    """Lazily import module/extension."""
+
+    def __init__(self, name, import_func):
+        super().__init__(name)
+        self.import_func = import_func
+        self.module = None
+
+    # Note:
+    # Python caches what was retrieved with `__getattr__`, so this method will not be
+    # called again for the same item.
+    def __getattr__(self, item):
+        self._import_once()
+        return getattr(self.module, item)
+
+    def __repr__(self):
+        if self.module is None:
+            return f"<module '{self.__module__}.{self.__class__.__name__}(\"{self.name}\")'>"
+        return repr(self.module)
+
+    def __dir__(self):
+        self._import_once()
+        return dir(self.module)
+
+    def _import_once(self):
+        if self.module is None:
+            self.module = self.import_func()
+            # Note:
+            # By attaching the module attributes to self,
+            # module attributes are directly accessible.
+            # This allows to avoid calling __getattr__ for every attribute access.
+            self.__dict__.update(self.module.__dict__)
+
+    def is_available(self):
+        try:
+            self._import_once()
+        except Exception:
+            return False
+        return True
+
+
+def _init_dll_path():
+    # On Windows Python-3.8+ has `os.add_dll_directory` call,
+    # which is called to configure dll search path.
+    # To find cuda related dlls we need to make sure the
+    # conda environment/bin path is configured Please take a look:
+    # https://stackoverflow.com/questions/59330863/cant-import-dll-module-in-python
+    # Please note: if some path can't be added using add_dll_directory we simply ignore this path
+    for path in os.environ.get("PATH", "").split(";"):
+        if os.path.exists(path):
+            try:
+                os.add_dll_directory(path)
+            except Exception:
+                pass
+
+
+def _check_cuda_version():
+    import torchaudio.lib._torchaudio
+
+    version = torchaudio.lib._torchaudio.cuda_version()
+    if version is not None and torch.version.cuda is not None:
+        version_str = str(version)
+        ta_version = f"{version_str[:-3]}.{version_str[-2]}"
+        t_version = torch.version.cuda.split(".")
+        t_version = f"{t_version[0]}.{t_version[1]}"
+        if ta_version != t_version:
+            raise RuntimeError(
+                "Detected that PyTorch and TorchAudio were compiled with different CUDA versions. "
+                f"PyTorch has CUDA version {t_version} whereas TorchAudio has CUDA version {ta_version}. "
+                "Please install the TorchAudio version that matches your PyTorch version."
+            )
+    return version

torchaudio/_internal/__init__.py

@@ -0,0 +1,10 @@
+try:
+    from .fb import download_url_to_file, load_state_dict_from_url
+except ImportError:
+    from torch.hub import download_url_to_file, load_state_dict_from_url
+
+
+__all__ = [
+    "load_state_dict_from_url",
+    "download_url_to_file",
+]

torchaudio/_internal/module_utils.py

@@ -0,0 +1,171 @@
+import importlib.util
+import os
+import warnings
+from functools import partial, wraps
+from typing import Optional
+
+
+def eval_env(var, default):
+    """Check if environment varable has True-y value"""
+    if var not in os.environ:
+        return default
+
+    val = os.environ.get(var, "0")
+    trues = ["1", "true", "TRUE", "on", "ON", "yes", "YES"]
+    falses = ["0", "false", "FALSE", "off", "OFF", "no", "NO"]
+    if val in trues:
+        return True
+    if val not in falses:
+        # fmt: off
+        raise RuntimeError(
+            f"Unexpected environment variable value `{var}={val}`. "
+            f"Expected one of {trues + falses}")
+        # fmt: on
+    return False
+
+
+def is_module_available(*modules: str) -> bool:
+    r"""Returns if a top-level module with :attr:`name` exists *without**
+    importing it. This is generally safer than try-catch block around a
+    `import X`. It avoids third party libraries breaking assumptions of some of
+    our tests, e.g., setting multiprocessing start method when imported
+    (see librosa/#747, torchvision/#544).
+    """
+    return all(importlib.util.find_spec(m) is not None for m in modules)
+
+
+def requires_module(*modules: str):
+    """Decorate function to give error message if invoked without required optional modules.
+
+    This decorator is to give better error message to users rather
+    than raising ``NameError:  name 'module' is not defined`` at random places.
+    """
+    missing = [m for m in modules if not is_module_available(m)]
+
+    if not missing:
+        # fall through. If all the modules are available, no need to decorate
+        def decorator(func):
+            return func
+
+    else:
+        req = f"module: {missing[0]}" if len(missing) == 1 else f"modules: {missing}"
+
+        def decorator(func):
+            @wraps(func)
+            def wrapped(*args, **kwargs):
+                raise RuntimeError(f"{func.__module__}.{func.__name__} requires {req}")
+
+            return wrapped
+
+    return decorator
+
+
+UNSUPPORTED = []
+
+
+def wrap_deprecated(func, name, direction: str, version: Optional[str] = None, remove: bool = False):
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        message = f"{name} has been deprecated. {direction}"
+        if remove:
+            message += f' It will be removed from {"a future" if version is None else "the " + str(version)} release. '
+        warnings.warn(message, stacklevel=2)
+        return func(*args, **kwargs)
+
+    return wrapped
+
+
+def deprecated(direction: str, version: Optional[str] = None, remove: bool = False):
+    """Decorator to add deprecation message
+
+    Args:
+        direction (str): Migration steps to be given to users.
+        version (str or int): The version when the object will be removed
+        remove (bool): If enabled, append future removal message.
+    """
+
+    def decorator(func):
+        wrapped = wrap_deprecated(func, f"{func.__module__}.{func.__name__}", direction, version=version, remove=remove)
+
+        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
+
+    .. warning::
+
+       {message}
+       {direction}
+
+    {func.__doc__}
+    """
+
+        return wrapped
+
+    return decorator
+
+
+DEPRECATION_MSG = (
+    "This deprecation is part of a large refactoring effort to transition TorchAudio into a maintenance phase. "
+    "Please see https://github.com/pytorch/audio/issues/3902 for more information."
+)
+
+IO_DEPRECATION_MSG = (
+    "This deprecation is part of a large refactoring effort to transition TorchAudio into a maintenance phase. "
+    "The decoding and encoding capabilities of PyTorch for both audio"
+    " and video are being consolidated into TorchCodec. "
+    "Please see https://github.com/pytorch/audio/issues/3902 for more information."
+)
+
+dropping_support = deprecated(DEPRECATION_MSG, version="2.9", remove=True)
+
+
+def dropping_class_support(c, msg=DEPRECATION_MSG):
+    c.__init__ = wrap_deprecated(c.__init__, f"{c.__module__}.{c.__name__}", msg, version="2.9", remove=True)
+    c.__doc__ = f"""DEPRECATED
+
+.. warning::
+
+    This class is deprecated from version 2.8. It will be removed in the 2.9 release.
+    {msg}
+{c.__doc__}
+"""
+
+    UNSUPPORTED.append(c)
+    return c
+
+
+def dropping_const_support(c, msg=DEPRECATION_MSG, name=None):
+    c.__doc__ = f"""[DEPRECATED]
+
+.. warning::
+
+    This object is deprecated deprecated from version 2.8. It will be removed in the 2.9 release.
+    {msg}
+{c.__doc__}
+    """
+    return c
+
+
+dropping_class_io_support = partial(dropping_class_support, msg=IO_DEPRECATION_MSG)
+
+dropping_io_support = deprecated(IO_DEPRECATION_MSG, version="2.9", remove=True)
+
+
+def fail_with_message(message):
+    """Generate decorator to give users message about missing TorchAudio extension."""
+
+    def decorator(func):
+        @wraps(func)
+        def wrapped(*args, **kwargs):
+            raise RuntimeError(f"{func.__module__}.{func.__name__} {message}")
+
+        return wrapped
+
+    return decorator
+
+
+def no_op(func):
+    """Op-op decorator. Used in place of fail_with_message when a functionality that requires extension works fine."""
+    return func