address feedback:

Author: Molly Xu

src/torchcodec/_core/CudaDeviceInterface.cpp

@@ -241,6 +241,8 @@ void CudaDeviceInterface::convertAVFrameToFrameOutput(
     std::optional<torch::Tensor> preAllocatedOutputTensor) {
   validatePreAllocatedTensorShape(preAllocatedOutputTensor, avFrame);
 
+  hasDecodedFrame_ = true;
+
   // All of our CUDA decoding assumes NV12 format. We handle non-NV12 formats by
   // converting them to NV12.
   avFrame = maybeConvertAVFrameToNV12OrRGB24(avFrame);
@@ -358,6 +360,10 @@ std::string CudaDeviceInterface::getDetails() {
   // Note: for this interface specifically the fallback is only known after a
   // frame has been decoded, not before: that's when FFmpeg decides to fallback,
   // so we can't know earlier.
+  if (!hasDecodedFrame_) {
+    return std::string(
+        "FFmpeg CUDA Device Interface. Fallback status unknown (no frames decoded).");
+  }
   return std::string("FFmpeg CUDA Device Interface. Using ") +
       (usingCPUFallback_ ? "CPU fallback." : "NVDEC.");
 }

src/torchcodec/_core/CudaDeviceInterface.h

@@ -63,6 +63,7 @@ class CudaDeviceInterface : public DeviceInterface {
   std::unique_ptr<FilterGraph> nv12Conversion_;
 
   bool usingCPUFallback_ = false;
+  bool hasDecodedFrame_ = false;
 };
 
 } // namespace facebook::torchcodec

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 FallbackInfo, VideoDecoder  # noqa
+from ._video_decoder import CpuFallbackStatus, VideoDecoder  # noqa
 
 SimpleVideoDecoder = VideoDecoder

src/torchcodec/decoders/_video_decoder.py

@@ -24,28 +24,28 @@
 
 
 @dataclass
-class FallbackInfo:
-    """Information about decoder fallback status.
+class CpuFallbackStatus:
+    """Information about CPU 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
+        - Use ``str(cpu_fallback_status)`` or ``print(cpu_fallback_status)`` to see the cpu fallback status
+        - Use ``bool(cpu_fallback_status)`` 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
+        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
+            self._nvcuvid_unavailable or self._video_not_supported
         )
 
     def __str__(self):
@@ -54,9 +54,9 @@ def __str__(self):
             return "Fallback status: Unknown"
 
         reasons = []
-        if self.__nvcuvid_unavailable:
+        if self._nvcuvid_unavailable:
             reasons.append("NVcuvid unavailable")
-        if self.__video_not_supported:
+        if self._video_not_supported:
             reasons.append("Video not supported")
 
         if reasons:
@@ -142,6 +142,10 @@ class VideoDecoder:
         stream_index (int): The stream index that this decoder is retrieving frames from. If a
             stream index was provided at initialization, this is the same value. If it was left
             unspecified, this is the :term:`best stream`.
+        cpu_fallback (CpuFallbackStatus): Information about whether the decoder fell back to CPU
+            decoding. Use ``bool(cpu_fallback)`` to check if fallback occurred, or
+            ``str(cpu_fallback)`` to get a human-readable status message. The status is only
+            determined after at least one frame has been decoded.
     """
 
     def __init__(
@@ -222,42 +226,33 @@ def __init__(
             custom_frame_mappings=custom_frame_mappings_data,
         )
 
-        self._fallback_info = FallbackInfo()
-        self._has_decoded_frame = False
+        self._cpu_fallback = CpuFallbackStatus()
 
     def __len__(self) -> int:
         return self._num_frames
 
     @property
-    def cpu_fallback(self) -> FallbackInfo:
+    def cpu_fallback(self) -> CpuFallbackStatus:
         # 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:
+        if not self._cpu_fallback.status_known:
             backend_details = core._get_backend_details(self._decoder)
 
-            self._fallback_info.status_known = True
+            if "status unknown" not in backend_details:
+                self._cpu_fallback.status_known = True
+
+                if "CPU fallback" in backend_details:
+                    if "NVCUVID not available" in backend_details:
+                        self._cpu_fallback._nvcuvid_unavailable = True
+                    else:
+                        self._cpu_fallback._video_not_supported = 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
+        return self._cpu_fallback
 
     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:
@@ -270,7 +265,6 @@ 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:
@@ -324,7 +318,6 @@ 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(),
@@ -344,7 +337,6 @@ 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,
@@ -374,7 +366,6 @@ 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:
@@ -404,7 +395,6 @@ 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(),
@@ -426,7 +416,6 @@ 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,
@@ -471,7 +460,6 @@ 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,19 +1737,6 @@ 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")
@@ -1767,6 +1754,8 @@ def test_cpu_fallback_h265_video_ffmpeg_cuda(self):
         # because its dimensions are too small
         decoder = VideoDecoder(H265_VIDEO.path, device="cuda")
 
+        assert not decoder.cpu_fallback.status_known
+
         _ = decoder.get_frame_at(0)
 
         assert decoder.cpu_fallback.status_known
@@ -1779,9 +1768,14 @@ def test_cpu_fallback_h265_video_beta_cuda(self):
         with set_cuda_backend("beta"):
             decoder = VideoDecoder(H265_VIDEO.path, device="cuda")
 
+        # Before accessing any frames, status should be unknown
+        assert decoder.cpu_fallback.status_known
+
         _ = decoder.get_frame_at(0)
 
+        # After accessing frames, status should be known
         assert decoder.cpu_fallback.status_known
+
         assert bool(decoder.cpu_fallback)
         assert "Fallback status: Falling back due to:" in str(decoder.cpu_fallback)