torchaudio 2.7.1__cp312-cp312-macosx_11_0_arm64.whl → 2.9.0__cp312-cp312-macosx_11_0_arm64.whl

torchaudio/__init__.py

@@ -1,30 +1,13 @@
+import os
+from typing import BinaryIO, Optional, Tuple, Union
+
+import torch
+
 # Initialize extension and backend first
 from . import _extension  # noqa  # usort: skip
-from ._backend import (  # noqa  # usort: skip
-    AudioMetaData,
-    get_audio_backend,
-    info,
-    list_audio_backends,
-    load,
-    save,
-    set_audio_backend,
-)
-
-from . import (  # noqa: F401
-    compliance,
-    datasets,
-    functional,
-    io,
-    kaldi_io,
-    models,
-    pipelines,
-    sox_effects,
-    transforms,
-    utils,
-)
-
-# For BC
-from . import backend  # 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
@@ -32,22 +15,190 @@ 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__ = [
-    "AudioMetaData",
     "load",
-    "info",
+    "load_with_torchcodec",
+    "save_with_torchcodec",
     "save",
-    "io",
     "compliance",
     "datasets",
     "functional",
     "models",
     "pipelines",
-    "kaldi_io",
     "utils",
-    "sox_effects",
     "transforms",
-    "list_audio_backends",
-    "get_audio_backend",
-    "set_audio_backend",
 ]

torchaudio/_extension/__init__.py

@@ -4,7 +4,7 @@ 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, _init_sox, _LazyImporter, _load_lib
+from .utils import _check_cuda_version, _init_dll_path, _load_lib
 
 _LG = logging.getLogger(__name__)
 
@@ -17,7 +17,6 @@ __all__ = [
     "_check_cuda_version",
     "_IS_TORCHAUDIO_EXT_AVAILABLE",
     "_IS_RIR_AVAILABLE",
-    "lazy_import_sox_ext",
 ]
 
 
@@ -44,18 +43,6 @@ if _IS_TORCHAUDIO_EXT_AVAILABLE:
     _IS_ALIGN_AVAILABLE = torchaudio.lib._torchaudio.is_align_available()
 
 
-_SOX_EXT = None
-
-
-def lazy_import_sox_ext():
-    """Load SoX integration based on availability in lazy manner"""
-
-    global _SOX_EXT
-    if _SOX_EXT is None:
-        _SOX_EXT = _LazyImporter("_torchaudio_sox", _init_sox)
-    return _SOX_EXT
-
-
 fail_if_no_rir = (
     no_op
     if _IS_RIR_AVAILABLE

torchaudio/_extension/utils.py

@@ -4,14 +4,12 @@ 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 importlib
 import logging
 import os
 import types
 from pathlib import Path
 
 import torch
-from torchaudio._internal.module_utils import eval_env
 
 _LG = logging.getLogger(__name__)
 _LIB_DIR = Path(__file__).parent.parent / "lib"
@@ -61,51 +59,6 @@ def _load_lib(lib: str) -> bool:
     return True
 
 
-def _import_sox_ext():
-    if os.name == "nt":
-        raise RuntimeError("sox extension is not supported on Windows")
-    if not eval_env("TORCHAUDIO_USE_SOX", True):
-        raise RuntimeError("sox extension is disabled. (TORCHAUDIO_USE_SOX=0)")
-
-    ext = "torchaudio.lib._torchaudio_sox"
-
-    if not importlib.util.find_spec(ext):
-        raise RuntimeError(
-            # fmt: off
-            "TorchAudio is not built with sox extension. "
-            "Please build TorchAudio with libsox support. (BUILD_SOX=1)"
-            # fmt: on
-        )
-
-    _load_lib("libtorchaudio_sox")
-    return importlib.import_module(ext)
-
-
-def _init_sox():
-    ext = _import_sox_ext()
-    ext.set_verbosity(0)
-
-    import atexit
-
-    torch.ops.torchaudio_sox.initialize_sox_effects()
-    atexit.register(torch.ops.torchaudio_sox.shutdown_sox_effects)
-
-    # Bundle functions registered with TORCH_LIBRARY into extension
-    # so that they can also be accessed in the same (lazy) manner
-    # from the extension.
-    keys = [
-        "get_info",
-        "load_audio_file",
-        "save_audio_file",
-        "apply_effects_tensor",
-        "apply_effects_file",
-    ]
-    for key in keys:
-        setattr(ext, key, getattr(torch.ops.torchaudio_sox, key))
-
-    return ext
-
-
 class _LazyImporter(types.ModuleType):
     """Lazily import module/extension."""
 

torchaudio/_internal/module_utils.py

@@ -1,7 +1,7 @@
 import importlib.util
 import os
 import warnings
-from functools import wraps
+from functools import partial, wraps
 from typing import Optional
 
 
@@ -60,6 +60,21 @@ def requires_module(*modules: str):
     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
 
@@ -70,31 +85,74 @@ def deprecated(direction: str, version: Optional[str] = None, remove: bool = Fal
     """
 
     def decorator(func):
-        @wraps(func)
-        def wrapped(*args, **kwargs):
-            message = f"{func.__module__}.{func.__name__} has been deprecated. {direction}"
-            if remove:
-                message += f' It will be removed from {"future" if version is None else version} release. '
-            warnings.warn(message, stacklevel=2)
-            return func(*args, **kwargs)
+        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: {func.__doc__}
+        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."""