Expose cpu_fallback in VideoDecoder API

src/torchcodec/decoders/__init__.py

@@ -7,6 +7,6 @@
 from .._core import AudioStreamMetadata, VideoStreamMetadata
 from ._audio_decoder import AudioDecoder  # noqa
 from ._decoder_utils import set_cuda_backend  # noqa
-from ._video_decoder import VideoDecoder  # noqa
+from ._video_decoder import FallbackInfo, VideoDecoder  # noqa
 
 SimpleVideoDecoder = VideoDecoder

src/torchcodec/decoders/_video_decoder.py

@@ -7,6 +7,7 @@
 import io
 import json
 import numbers
+from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Literal, Optional, Sequence, Tuple, Union
 
@@ -22,6 +23,47 @@
 from torchcodec.transforms import DecoderTransform, Resize
 
 
+@dataclass
+class FallbackInfo:
+    """Information about decoder fallback status.
+
+    This class tracks whether the decoder fell back to CPU decoding.
+
+    Usage:
+        - Use ``str(fallback_info)`` or ``print(fallback_info)`` to see the cpu fallback status
+        - Use ``bool(fallback_info)`` to check if any fallback occurred
+
+    Attributes:
+        status_known (bool): Whether the fallback status has been determined.
+    """
+
+    def __init__(self):
+        self.status_known = False
+        self.__nvcuvid_unavailable = False
+        self.__video_not_supported = False
+
+    def __bool__(self):
+        """Returns True if fallback occurred."""
+        return self.status_known and (
+            self.__nvcuvid_unavailable or self.__video_not_supported
+        )
+
+    def __str__(self):
+        """Returns a human-readable string representation of the cpu fallback status."""
+        if not self.status_known:
+            return "Fallback status: Unknown"
+
+        reasons = []
+        if self.__nvcuvid_unavailable:
+            reasons.append("NVcuvid unavailable")
+        if self.__video_not_supported:
+            reasons.append("Video not supported")
+
+        if reasons:
+            return "Fallback status: Falling back due to: " + ", ".join(reasons)
+        return "Fallback status: No fallback required"
+
+
 class VideoDecoder:
     """A single-stream video decoder.
 
@@ -180,13 +222,42 @@ def __init__(
             custom_frame_mappings=custom_frame_mappings_data,
         )
 
+        self._fallback_info = FallbackInfo()
+        self._has_decoded_frame = False
+
     def __len__(self) -> int:
         return self._num_frames
 
+    @property
+    def cpu_fallback(self) -> FallbackInfo:
+        # We can only determine whether fallback to CPU is happening when this
+        # property is accessed and requires that at least one frame has been decoded.
+        self._update_cpu_fallback()
+        return self._fallback_info
+
+    def _update_cpu_fallback(self):
+        """Update the fallback status if it hasn't been determined yet.
+
+        This method queries the C++ backend to determine if fallback to CPU
+        decoding occurred. The query is only performed after at least one frame
+        has been decoded.
+        """
+        if not self._fallback_info.status_known and self._has_decoded_frame:
+            backend_details = core._get_backend_details(self._decoder)
+
+            self._fallback_info.status_known = True
+
+            if "CPU fallback" in backend_details:
+                if "NVCUVID not available" in backend_details:
+                    self._fallback_info._FallbackInfo__nvcuvid_unavailable = True
+                else:
+                    self._fallback_info._FallbackInfo__video_not_supported = True
+
     def _getitem_int(self, key: int) -> Tensor:
         assert isinstance(key, int)
 
         frame_data, *_ = core.get_frame_at_index(self._decoder, frame_index=key)
+        self._has_decoded_frame = True
         return frame_data
 
     def _getitem_slice(self, key: slice) -> Tensor:
@@ -199,6 +270,7 @@ def _getitem_slice(self, key: slice) -> Tensor:
             stop=stop,
             step=step,
         )
+        self._has_decoded_frame = True
         return frame_data
 
     def __getitem__(self, key: Union[numbers.Integral, slice]) -> Tensor:
@@ -252,6 +324,7 @@ def get_frame_at(self, index: int) -> Frame:
         data, pts_seconds, duration_seconds = core.get_frame_at_index(
             self._decoder, frame_index=index
         )
+        self._has_decoded_frame = True
         return Frame(
             data=data,
             pts_seconds=pts_seconds.item(),
@@ -271,6 +344,7 @@ def get_frames_at(self, indices: Union[torch.Tensor, list[int]]) -> FrameBatch:
         data, pts_seconds, duration_seconds = core.get_frames_at_indices(
             self._decoder, frame_indices=indices
         )
+        self._has_decoded_frame = True
 
         return FrameBatch(
             data=data,
@@ -300,6 +374,7 @@ def get_frames_in_range(self, start: int, stop: int, step: int = 1) -> FrameBatc
             stop=stop,
             step=step,
         )
+        self._has_decoded_frame = True
         return FrameBatch(*frames)
 
     def get_frame_played_at(self, seconds: float) -> Frame:
@@ -329,6 +404,7 @@ def get_frame_played_at(self, seconds: float) -> Frame:
         data, pts_seconds, duration_seconds = core.get_frame_at_pts(
             self._decoder, seconds
         )
+        self._has_decoded_frame = True
         return Frame(
             data=data,
             pts_seconds=pts_seconds.item(),
@@ -350,6 +426,7 @@ def get_frames_played_at(
         data, pts_seconds, duration_seconds = core.get_frames_by_pts(
             self._decoder, timestamps=seconds
         )
+        self._has_decoded_frame = True
         return FrameBatch(
             data=data,
             pts_seconds=pts_seconds,
@@ -394,6 +471,7 @@ def get_frames_played_in_range(
             start_seconds=start_seconds,
             stop_seconds=stop_seconds,
         )
+        self._has_decoded_frame = True
         return FrameBatch(*frames)
 
 

test/test_decoders.py

@@ -1737,6 +1737,92 @@ def test_set_cuda_backend(self):
                 with set_cuda_backend(backend):
                     VideoDecoder(H265_VIDEO.path, device=f"cuda:{bad_device_number}")
 
+    def test_cpu_fallback_before_after_decoding(self):
+        decoder = VideoDecoder(NASA_VIDEO.path)
+
+        # Before accessing any frames, status should be unknown
+        assert not decoder.cpu_fallback.status_known
+        assert str(decoder.cpu_fallback) == "Fallback status: Unknown"
+        assert not bool(decoder.cpu_fallback)
+
+        # After accessing frames, status should be known
+        _ = decoder[0]
+        assert decoder.cpu_fallback.status_known
+        assert str(decoder.cpu_fallback) != "Fallback status: Unknown"
+
+    def test_cpu_fallback_no_fallback_on_cpu_device(self):
+        """Test that CPU device doesn't trigger fallback (it's not a fallback scenario)."""
+        decoder = VideoDecoder(NASA_VIDEO.path, device="cpu")
+
+        _ = decoder[0]
+
+        assert decoder.cpu_fallback.status_known
+        assert not bool(decoder.cpu_fallback)
+        assert "No fallback required" in str(decoder.cpu_fallback)
+
+    @needs_cuda
+    def test_cpu_fallback_h265_video_ffmpeg_cuda(self):
+        """Test that H265 video triggers CPU fallback on FFmpeg CUDA interface."""
+        # H265_VIDEO is known to trigger CPU fallback on FFmpeg CUDA
+        # because its dimensions are too small
+        decoder = VideoDecoder(H265_VIDEO.path, device="cuda")
+
+        _ = decoder.get_frame_at(0)
+
+        assert decoder.cpu_fallback.status_known
+        assert bool(decoder.cpu_fallback)
+        assert "Fallback status: Falling back due to:" in str(decoder.cpu_fallback)
+
+    @needs_cuda
+    def test_cpu_fallback_h265_video_beta_cuda(self):
+        """Test that H265 video triggers CPU fallback on Beta CUDA interface."""
+        with set_cuda_backend("beta"):
+            decoder = VideoDecoder(H265_VIDEO.path, device="cuda")
+
+        _ = decoder.get_frame_at(0)
+
+        assert decoder.cpu_fallback.status_known
+        assert bool(decoder.cpu_fallback)
+        assert "Fallback status: Falling back due to:" in str(decoder.cpu_fallback)
+
+    @needs_cuda
+    def test_cpu_fallback_no_fallback_on_supported_video(self):
+        """Test that supported videos don't trigger fallback on CUDA."""
+        decoder = VideoDecoder(NASA_VIDEO.path, device="cuda")
+
+        _ = decoder[0]
+
+        assert not bool(decoder.cpu_fallback)
+        assert "No fallback required" in str(decoder.cpu_fallback)
+
+    def test_cpu_fallback_status_cached(self):
+        """Test that cpu_fallback status is determined once and then cached."""
+        decoder = VideoDecoder(NASA_VIDEO.path)
+
+        _ = decoder[0]
+        first_status = str(decoder.cpu_fallback)
+        assert decoder.cpu_fallback.status_known
+
+        _ = decoder[1]
+        second_status = str(decoder.cpu_fallback)
+        assert decoder.cpu_fallback.status_known
+
+        assert first_status == second_status
+
+    def test_cpu_fallback_multiple_access_methods(self):
+        """Test that cpu_fallback works with different frame access methods."""
+        decoder = VideoDecoder(NASA_VIDEO.path)
+
+        _ = decoder.get_frame_at(0)
+        assert decoder.cpu_fallback.status_known
+        status_after_get_frame = str(decoder.cpu_fallback)
+
+        _ = decoder.get_frames_in_range(1, 3)
+        assert str(decoder.cpu_fallback) == status_after_get_frame
+
+        _ = decoder.get_frame_played_at(0.5)
+        assert str(decoder.cpu_fallback) == status_after_get_frame
+
 
 class TestAudioDecoder:
     @pytest.mark.parametrize("asset", (NASA_AUDIO, NASA_AUDIO_MP3, SINE_MONO_S32))