Update deprecation wording, add warnings to main pages (#3955)

NicolasHug · web-flow · commit 70caf76066ef · 2025-07-02T12:45:58.000+01:00
diff --git a/README.md b/README.md
@@ -10,7 +10,8 @@ torchaudio: an audio library for PyTorch
 > [!NOTE]
 > **We are in the process of refactoring TorchAudio and transitioning it into a
 >  maintenance phase. This process will include removing some user-facing
->  features. Our main goals are to reduce redundancies with the rest of the
+>  features: those features are deprecated from TorchAudio 2.8 and will be removed in 2.9.
+>  Our main goals are to reduce redundancies with the rest of the
 >  PyTorch ecosystem, make it easier to maintain, and create a version of
 >  TorchAudio that is more tightly scoped to its strengths: processing audio
 >  data for ML. Please see
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,6 +7,17 @@ Torchaudio is a library for audio and signal processing with PyTorch.
 It provides I/O, signal and data processing functions, datasets,
 model implementations and application components.
 
+.. note::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - Some APIs are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
+
 ..
    Generate Table Of Contents (left navigation bar)
    NOTE: If you are adding tutorials, add entries to toctree and customcarditem below
diff --git a/docs/source/io.rst b/docs/source/io.rst
@@ -3,6 +3,16 @@
 torchaudio.io
 =============
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The ``torchaudio.io`` module is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 .. currentmodule:: torchaudio.io
 
 .. autosummary::
diff --git a/docs/source/kaldi_io.rst b/docs/source/kaldi_io.rst
@@ -8,6 +8,11 @@ torchaudio.kaldi_io
 
 .. currentmodule:: torchaudio.kaldi_io
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``kaldi_io`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 To use this module, the dependency kaldi_io_ needs to be installed.
 This is a light wrapper around ``kaldi_io`` that returns :class:`torch.Tensor`.
 
diff --git a/docs/source/libtorio.rst b/docs/source/libtorio.rst
@@ -1,9 +1,16 @@
 libtorio
 ========
 
+
 .. warning::
-   TorchAudio's C++ API is a prototype feature.
-   API/ABI backward compatibility is not guaranteed.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 .. toctree::
    libtorio.stream_reader
diff --git a/docs/source/libtorio.stream_reader.rst b/docs/source/libtorio.stream_reader.rst
@@ -1,6 +1,13 @@
+
 .. warning::
-   TorchAudio's C++ API is a prototype feature.
-   API/ABI backward compatibility is not guaranteed.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 
 .. note::
diff --git a/docs/source/libtorio.stream_writer.rst b/docs/source/libtorio.stream_writer.rst
@@ -1,7 +1,13 @@
+
 .. warning::
-   TorchAudio's C++ API is prototype feature.
-   API/ABI backward compatibility is not guaranteed.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 .. note::
    The top-level namespace has been changed from ``torchaudio`` to ``torio``.
diff --git a/docs/source/prototype.datasets.rst b/docs/source/prototype.datasets.rst
@@ -5,6 +5,11 @@ torchaudio.prototype.datasets
 
 .. currentmodule:: torchaudio.prototype.datasets
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 .. autosummary::
     :toctree: generated
     :nosignatures:
diff --git a/docs/source/prototype.functional.rst b/docs/source/prototype.functional.rst
@@ -4,6 +4,11 @@ torchaudio.prototype.functional
 .. py:module:: torchaudio.prototype.functional
 .. currentmodule:: torchaudio.prototype.functional
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 Utility
 ~~~~~~~
 
diff --git a/docs/source/prototype.models.rst b/docs/source/prototype.models.rst
@@ -4,6 +4,10 @@ torchaudio.prototype.models
 .. py:module:: torchaudio.prototype.models
 .. currentmodule:: torchaudio.prototype.models
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
 
 The ``torchaudio.prototype.models`` subpackage contains definitions of models for addressing common audio tasks.
 
diff --git a/docs/source/prototype.pipelines.rst b/docs/source/prototype.pipelines.rst
@@ -5,6 +5,11 @@ torchaudio.prototype.pipelines
 .. py:module:: torchaudio.prototype.pipelines
 .. currentmodule:: torchaudio.prototype.pipelines
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 The pipelines subpackage contains APIs to models with pretrained weights and relevant utilities.
 
 RNN-T Streaming/Non-Streaming ASR
diff --git a/docs/source/prototype.rst b/docs/source/prototype.rst
@@ -2,8 +2,9 @@ torchaudio.prototype
 ====================
 
 .. warning::
-    As TorchAudio is no longer being actively developed, this functionality will no longer be supported.
-    See https://github.com/pytorch/audio/issues/3902 for more details.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
 
 ``torchaudio.prototype`` provides prototype features;
 they are at an early stage for feedback and testing.
diff --git a/docs/source/prototype.transforms.rst b/docs/source/prototype.transforms.rst
@@ -5,6 +5,11 @@ torchaudio.prototype.transforms
 
 .. currentmodule:: torchaudio.prototype.transforms
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``prototype`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 .. autosummary::
     :toctree: generated
     :nosignatures:
diff --git a/docs/source/sox_effects.rst b/docs/source/sox_effects.rst
@@ -5,6 +5,11 @@ torchaudio.sox_effects
 
 .. currentmodule:: torchaudio.sox_effects
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result, the ``sox_effect`` module is
+    deprecated in 2.8 and will be removed in 2.9.
+
 Applying effects
 ----------------
 
diff --git a/docs/source/torchaudio.rst b/docs/source/torchaudio.rst
@@ -3,6 +3,16 @@ torchaudio
 
 .. currentmodule:: torchaudio
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs listed below are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 I/O
 ---
 
diff --git a/docs/source/torio.io.rst b/docs/source/torio.io.rst
@@ -5,6 +5,16 @@ torio.io
 
 .. currentmodule:: torio.io
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 .. autosummary::
    :toctree: generated
    :nosignatures:
diff --git a/docs/source/torio.rst b/docs/source/torio.rst
@@ -5,6 +5,16 @@ torio
 
 .. currentmodule:: torio.io
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 ``torio`` is an alternative top-level module for I/O features. It is the extraction of the core implementation of I/O feature of ``torchaudio``.
 
 If you want to use the multimedia processing features, but do not want to depend on the entire ``torchaudio`` package, you can use ``torio``.
diff --git a/docs/source/torio.utils.rst b/docs/source/torio.utils.rst
@@ -5,6 +5,16 @@ torio.utils
 
 ``torio.utils`` module contains utility functions to query and configure the global state of third party libraries.
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - ``torio`` is deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 .. currentmodule:: torio.utils
 
 .. autosummary::
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -5,6 +5,14 @@ torchaudio.utils
 
 ``torchaudio.utils`` module contains utility functions to configure the global state of third party libraries.
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+    - ``sox_utils`` and `ffmpeg_utils`` are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 .. currentmodule:: torchaudio.utils
 
 .. autosummary::
diff --git a/examples/tutorials/additive_synthesis_tutorial.py b/examples/tutorials/additive_synthesis_tutorial.py
@@ -5,6 +5,16 @@
 
 **Author**: `Moto Hira <moto@meta.com>`__
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 This tutorial is the continuation of
 `Oscillator and ADSR Envelope <./oscillator_tutorial.html>`__.
 
diff --git a/examples/tutorials/asr_inference_with_cuda_ctc_decoder_tutorial.py b/examples/tutorials/asr_inference_with_cuda_ctc_decoder_tutorial.py
@@ -4,6 +4,16 @@
 
 **Author**: `Yuekai Zhang <yuekaiz@nvidia.com>`__
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 This tutorial shows how to perform speech recognition inference using a
 CUDA-based CTC beam search decoder.
 We demonstrate this on a pretrained
diff --git a/examples/tutorials/audio_io_tutorial.py b/examples/tutorials/audio_io_tutorial.py
@@ -9,8 +9,14 @@
 load them into PyTorch Tensors and save PyTorch Tensors.
 
 .. warning::
-    IO functionality within TorchAudio has been superseded by `AudioDecoder` from the TorchCodec library.
-    See https://github.com/pytorch/audio/issues/3902 for more details.`.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 """
 
diff --git a/examples/tutorials/ctc_forced_alignment_api_tutorial.py b/examples/tutorials/ctc_forced_alignment_api_tutorial.py
@@ -5,8 +5,14 @@
 **Author**: `Xiaohui Zhang <xiaohuizhang@meta.com>`__, `Moto Hira <moto@meta.com>`__
 
 .. warning::
-    As TorchAudio is no longer being actively developed, this functionality will no longer be supported.
-    See https://github.com/pytorch/audio/issues/3902 for more details.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 The forced alignment is a process to align transcript with speech.
 This tutorial shows how to align transcripts to speech using
diff --git a/examples/tutorials/effector_tutorial.py b/examples/tutorials/effector_tutorial.py
@@ -5,8 +5,14 @@
 **Author**: `Moto Hira <moto@meta.com>`__
 
 .. warning::
-    As TorchAudio is no longer being actively developed, this functionality will no longer be supported.
-    See https://github.com/pytorch/audio/issues/3902 for more details.
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
 
 This tutorial shows how to use :py:class:`torchaudio.io.AudioEffector` to
 apply various effects and codecs to waveform tensor.
diff --git a/examples/tutorials/filter_design_tutorial.py b/examples/tutorials/filter_design_tutorial.py
@@ -4,6 +4,16 @@
 
 **Author**: `Moto Hira <moto@meta.com>`__
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 This tutorial shows how to create basic digital filters
 (impulse responses) and their properties.
 
diff --git a/examples/tutorials/forced_alignment_for_multilingual_data_tutorial.py b/examples/tutorials/forced_alignment_for_multilingual_data_tutorial.py
@@ -4,6 +4,16 @@
 
 **Authors**: `Xiaohui Zhang <xiaohuizhang@meta.com>`__, `Moto Hira <moto@meta.com>`__.
 
+.. warning::
+    Starting with version 2.8, we are refactoring TorchAudio to transition it
+    into a maintenance phase. As a result:
+
+    - The APIs described in this tutorial are deprecated in 2.8 and will be removed in 2.9.
+    - 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.
+
 This tutorial shows how to align transcript to speech for non-English languages.
 
 The process of aligning non-English (normalized) transcript is identical to aligning
diff --git a/examples/tutorials/forced_alignment_tutorial.py b/examples/tutorials/forced_alignment_tutorial.py
diff --git a/examples/tutorials/nvdec_tutorial.py b/examples/tutorials/nvdec_tutorial.py
diff --git a/examples/tutorials/nvenc_tutorial.py b/examples/tutorials/nvenc_tutorial.py
diff --git a/examples/tutorials/oscillator_tutorial.py b/examples/tutorials/oscillator_tutorial.py
diff --git a/examples/tutorials/streamreader_advanced_tutorial.py b/examples/tutorials/streamreader_advanced_tutorial.py
diff --git a/examples/tutorials/streamreader_basic_tutorial.py b/examples/tutorials/streamreader_basic_tutorial.py
diff --git a/examples/tutorials/streamwriter_advanced.py b/examples/tutorials/streamwriter_advanced.py
diff --git a/examples/tutorials/streamwriter_basic_tutorial.py b/examples/tutorials/streamwriter_basic_tutorial.py
diff --git a/examples/tutorials/subtractive_synthesis_tutorial.py b/examples/tutorials/subtractive_synthesis_tutorial.py
diff --git a/src/torchaudio/_internal/module_utils.py b/src/torchaudio/_internal/module_utils.py
diff --git a/src/torchaudio/utils/sox_utils.py b/src/torchaudio/utils/sox_utils.py
diff --git a/src/torio/utils/ffmpeg_utils.py b/src/torio/utils/ffmpeg_utils.py
