Add deprecation warnings for video stuff

Author: NicolasHug

docs/source/io.rst

@@ -91,12 +91,11 @@ Video
 
 .. warning::
 
-    Torchvision supports video decoding through different APIs listed below,
-    some of which are still in BETA stage. In the near future, we intend to
-    centralize PyTorch's video decoding capabilities within the `torchcodec
-    <https://github.com/pytorch/torchcodec>`_ project. We encourage you to try
-    it out and share your feedback, as the torchvision video decoders will
-    eventually be deprecated.
+    DEPRECATED: All the video decoding and encoding capabilities of torchvision
+    are deprecated from version 0.22 and will be removed in version 0.24.  We
+    recommend that you migrate to
+    `TorchCodec<https://github.com/pytorch/torchcodec>`_, where we'll
+    consolidate the future decoding/encoding capabilities of PyTorch
 
 .. autosummary::
     :toctree: generated/

torchvision/io/_video_opt.py

@@ -185,6 +185,7 @@ def _read_video_from_file(
         info (Dict): metadata for the video and audio. Can contain the fields video_fps (float)
             and audio_fps (int)
     """
+    _raise_video_deprecation_warning()
     _validate_pts(video_pts_range)
     _validate_pts(audio_pts_range)
 
@@ -256,6 +257,7 @@ def _probe_video_from_file(filename: str) -> VideoMetaData:
     """
     Probe a video file and return VideoMetaData with info about the video
     """
+    _raise_video_deprecation_warning()
     result = torch.ops.video_reader.probe_video_from_file(filename)
     vtimebase, vfps, vduration, atimebase, asample_rate, aduration = result
     info = _fill_info(vtimebase, vfps, vduration, atimebase, asample_rate, aduration)
@@ -331,6 +333,7 @@ def _read_video_from_memory(
             `K` is the number of channels
     """
 
+    _raise_video_deprecation_warning()
     _validate_pts(video_pts_range)
     _validate_pts(audio_pts_range)
 
@@ -405,6 +408,7 @@ def _read_video_timestamps_from_memory(
         0,  # audio_timebase_num
         1,  # audio_timebase_den
     )
+    _raise_video_deprecation_warning()
     _vframes, vframe_pts, vtimebase, vfps, vduration, _aframes, aframe_pts, atimebase, asample_rate, aduration = result
     info = _fill_info(vtimebase, vfps, vduration, atimebase, asample_rate, aduration)
 
@@ -420,6 +424,7 @@ def _probe_video_from_memory(
     Probe a video in memory and return VideoMetaData with info about the video
     This function is torchscriptable
     """
+    _raise_video_deprecation_warning()
     if not isinstance(video_data, torch.Tensor):
         with warnings.catch_warnings():
             # Ignore the warning because we actually don't modify the buffer in this function
@@ -437,6 +442,7 @@ def _read_video(
     end_pts: Optional[Union[float, Fraction]] = None,
     pts_unit: str = "pts",
 ) -> Tuple[torch.Tensor, torch.Tensor, Dict[str, float]]:
+    _raise_video_deprecation_warning()
     if end_pts is None:
         end_pts = float("inf")
 
@@ -495,6 +501,7 @@ def get_pts(time_base):
 def _read_video_timestamps(
     filename: str, pts_unit: str = "pts"
 ) -> Tuple[Union[List[int], List[Fraction]], Optional[float]]:
+    _raise_video_deprecation_warning()
     if pts_unit == "pts":
         warnings.warn(
             "The pts_unit 'pts' gives wrong results and will be removed in a "

torchvision/io/video.py

@@ -11,6 +11,7 @@
 
 from ..utils import _log_api_usage_once
 from . import _video_opt
+from ._video_deprecation_warning import _raise_video_deprecation_warning
 
 try:
     import av
@@ -66,7 +67,15 @@ def write_video(
     audio_options: Optional[Dict[str, Any]] = None,
 ) -> None:
     """
-    Writes a 4d tensor in [T, H, W, C] format in a video file.
+    [DEPRECATED] Writes a 4d tensor in [T, H, W, C] format in a video file.
+
+    .. warning::
+
+        DEPRECATED: All the video decoding and encoding capabilities of torchvision
+        are deprecated from version 0.22 and will be removed in version 0.24.  We
+        recommend that you migrate to
+        `TorchCodec<https://github.com/pytorch/torchcodec>`_, where we'll
+        consolidate the future decoding/encoding capabilities of PyTorch
 
     This function relies on PyAV (therefore, ultimately FFmpeg) to encode
     videos, you can get more fine-grained control by referring to the other
@@ -107,6 +116,7 @@ def write_video(
         >>> write_video("video.mp4", options = {"crf": "17"})
 
     """
+    _raise_video_deprecation_warning()
     if not torch.jit.is_scripting() and not torch.jit.is_tracing():
         _log_api_usage_once(write_video)
     _check_av_available()
@@ -276,16 +286,15 @@ def read_video(
     pts_unit: str = "pts",
     output_format: str = "THWC",
 ) -> Tuple[torch.Tensor, torch.Tensor, Dict[str, Any]]:
-    """
-    Reads a video from a file, returning both the video frames and the audio frames
+    """[DEPRECATED] Reads a video from a file, returning both the video frames and the audio frames
 
     .. warning::
 
-        In the near future, we intend to centralize PyTorch's video decoding
-        capabilities within the `torchcodec
-        <https://github.com/pytorch/torchcodec>`_ project. We encourage you to
-        try it out and share your feedback, as the torchvision video decoders
-        will eventually be deprecated.
+        DEPRECATED: All the video decoding and encoding capabilities of torchvision
+        are deprecated from version 0.22 and will be removed in version 0.24.  We
+        recommend that you migrate to
+        `TorchCodec<https://github.com/pytorch/torchcodec>`_, where we'll
+        consolidate the future decoding/encoding capabilities of PyTorch
 
     Args:
         filename (str): path to the video file. If using the pyav backend, this can be whatever ``av.open`` accepts.
@@ -302,6 +311,7 @@ def read_video(
         aframes (Tensor[K, L]): the audio frames, where `K` is the number of channels and `L` is the number of points
         info (Dict): metadata for the video and audio. Can contain the fields video_fps (float) and audio_fps (int)
     """
+    _raise_video_deprecation_warning()
     if not torch.jit.is_scripting() and not torch.jit.is_tracing():
         _log_api_usage_once(read_video)
 
@@ -408,16 +418,15 @@ def _decode_video_timestamps(container: "av.container.Container") -> List[int]:
 
 
 def read_video_timestamps(filename: str, pts_unit: str = "pts") -> Tuple[List[int], Optional[float]]:
-    """
-    List the video frames timestamps.
+    """[DEPREACTED] List the video frames timestamps.
 
     .. warning::
 
-        In the near future, we intend to centralize PyTorch's video decoding
-        capabilities within the `torchcodec
-        <https://github.com/pytorch/torchcodec>`_ project. We encourage you to
-        try it out and share your feedback, as the torchvision video decoders
-        will eventually be deprecated.
+        DEPRECATED: All the video decoding and encoding capabilities of torchvision
+        are deprecated from version 0.22 and will be removed in version 0.24.  We
+        recommend that you migrate to
+        `TorchCodec<https://github.com/pytorch/torchcodec>`_, where we'll
+        consolidate the future decoding/encoding capabilities of PyTorch
 
     Note that the function decodes the whole video frame-by-frame.
 
@@ -432,6 +441,7 @@ def read_video_timestamps(filename: str, pts_unit: str = "pts") -> Tuple[List[in
         video_fps (float, optional): the frame rate for the video
 
     """
+    _raise_video_deprecation_warning()
     if not torch.jit.is_scripting() and not torch.jit.is_tracing():
         _log_api_usage_once(read_video_timestamps)
     from torchvision import get_video_backend

torchvision/io/video_reader.py

@@ -45,20 +45,19 @@ def _has_video_opt() -> bool:
 
 
 class VideoReader:
-    """
-    Fine-grained video-reading API.
+    """[DEPRECATED] Fine-grained video-reading API.
     Supports frame-by-frame reading of various streams from a single video
     container. Much like previous video_reader API it supports the following
     backends: video_reader, pyav, and cuda.
     Backends can be set via `torchvision.set_video_backend` function.
 
     .. warning::
 
-        In the near future, we intend to centralize PyTorch's video decoding
-        capabilities within the `torchcodec
-        <https://github.com/pytorch/torchcodec>`_ project. We encourage you to
-        try it out and share your feedback, as the torchvision video decoders
-        will eventually be deprecated.
+        DEPRECATED: All the video decoding and encoding capabilities of torchvision
+        are deprecated from version 0.22 and will be removed in version 0.24.  We
+        recommend that you migrate to
+        `TorchCodec<https://github.com/pytorch/torchcodec>`_, where we'll
+        consolidate the future decoding/encoding capabilities of PyTorch
 
     .. betastatus:: VideoReader class
 
@@ -125,6 +124,7 @@ def __init__(
         stream: str = "video",
         num_threads: int = 0,
     ) -> None:
+        _raise_video_deprecation_warning()
         _log_api_usage_once(self)
         from .. import get_video_backend