[torchcodec] Add properties for duration and average_fps (#122)

Summary:
Pull Request resolved: #122

These properties use the content data if possible. Otherwise they fallback to the header data.

Reviewed By: NicolasHug

Differential Revision: D60384168

fbshipit-source-id: e1a6cd10652d9000d306ec4400e736b8dd338cf5

Author: ahmadsharif1

src/torchcodec/decoders/_core/_metadata.py

@@ -23,8 +23,9 @@
 class VideoStreamMetadata:
     """Metadata of a single video stream."""
 
-    duration_seconds: Optional[float]
-    """Duration of the stream, in seconds (float or None)."""
+    duration_seconds_from_header: Optional[float]
+    """Duration of the stream, in seconds obtained from the header (float or
+    None). This could be inaccurate."""
     bit_rate: Optional[float]
     """Bit rate of the stream, in seconds (float or None)."""
     num_frames_from_header: Optional[int]
@@ -36,17 +37,27 @@ class VideoStreamMetadata:
     content (the scan doesn't involve decoding). This is more accurate
     than ``num_frames_from_header``. We recommend using the
     ``num_frames`` attribute instead. (int or None)."""
-    min_pts_seconds: Optional[float]
-    """Minimum :term:`pts` of any frame in the stream (float or None)."""
-    max_pts_seconds: Optional[float]
-    """Maximum :term:`pts` of any frame in the stream (float or None)."""
+    begin_stream_from_content_seconds: Optional[float]
+    """Beginning of the stream in seconds (float or None).
+    This is min(frame.pts) for all frames in this stream."""
+    end_stream_from_content_seconds: Optional[float]
+    """End of the stream in seconds (float or None).
+    This is max(frame.pts + frame.duration) for all frames in this stream.
+    Note that frames have a pts and duration and the interval defined by
+    [pts, pts + duration) is a half-open interval (the right boundary is open).
+    Therefore no frame is displayed at this time value.
+    Calling
+    SimpleVideoDecoder.get_frame_displayed_at(end_stream_from_content_seconds)
+    will raise a StopIteration exception.
+    If you want to get the last frame you can use [-1] on a SimpleVideoDecoder
+    object."""
     codec: Optional[str]
     """Codec (str or None)."""
     width: Optional[int]
     """Width of the frames (int or None)."""
     height: Optional[int]
     """Height of the frames (int or None)."""
-    average_fps: Optional[float]
+    average_fps_from_header: Optional[float]
     """Averate fps of the stream (float or None)."""
     stream_index: int
     """Index of the stream within the video (int)."""
@@ -62,11 +73,46 @@ def num_frames(self) -> Optional[int]:
         else:
             return self.num_frames_from_header
 
+    @property
+    def duration_seconds(self) -> Optional[float]:
+        """Duration of the stream in seconds. We try to calculate the duration
+        from the actual frames if we scanned the frames. Otherwise we fall back
+        to the duration obtained from the header.
+        """
+        if (
+            self.end_stream_from_content_seconds is None
+            or self.begin_stream_from_content_seconds is None
+        ):
+            return self.duration_seconds_from_header
+        return (
+            self.end_stream_from_content_seconds
+            - self.begin_stream_from_content_seconds
+        )
+
+    @property
+    def average_fps(self) -> Optional[float]:
+        """Average fps of the stream. We try to get the average fps from the
+        actual frames if we scanned the frames. Otherwise we fall back to the
+        fps obtained from the header.
+        """
+        if (
+            self.end_stream_from_content_seconds is None
+            or self.begin_stream_from_content_seconds is None
+            or self.num_frames is None
+        ):
+            return self.average_fps_from_header
+        return self.num_frames / (
+            self.end_stream_from_content_seconds
+            - self.begin_stream_from_content_seconds
+        )
+
     def __repr__(self):
-        # Overridden because `num_frames` wouldn't be printed by default.
+        # Overridden because properites are not printed by default.
         s = self.__class__.__name__ + ":\n"
         spaces = "  "
         s += f"{spaces}num_frames: {self.num_frames}\n"
+        s += f"{spaces}duration_seconds: {self.duration_seconds}\n"
+        s += f"{spaces}average_fps: {self.average_fps}\n"
         for field in dataclasses.fields(self):
             s += f"{spaces}{field.name}: {getattr(self, field.name)}\n"
         return s
@@ -109,18 +155,22 @@ def get_video_metadata(decoder: torch.Tensor) -> VideoMetadata:
         stream_dict = json.loads(_get_stream_json_metadata(decoder, stream_index))
         streams_metadata.append(
             VideoStreamMetadata(
-                duration_seconds=stream_dict.get("durationSeconds"),
+                duration_seconds_from_header=stream_dict.get("durationSeconds"),
                 bit_rate=stream_dict.get("bitRate"),
                 # TODO_OPEN_ISSUE: We should align the C++ names and the json
                 # keys with the Python names
                 num_frames_from_header=stream_dict.get("numFrames"),
                 num_frames_from_content=stream_dict.get("numFramesFromScan"),
-                min_pts_seconds=stream_dict.get("minPtsSecondsFromScan"),
-                max_pts_seconds=stream_dict.get("maxPtsSecondsFromScan"),
+                begin_stream_from_content_seconds=stream_dict.get(
+                    "minPtsSecondsFromScan"
+                ),
+                end_stream_from_content_seconds=stream_dict.get(
+                    "maxPtsSecondsFromScan"
+                ),
                 codec=stream_dict.get("codec"),
                 width=stream_dict.get("width"),
                 height=stream_dict.get("height"),
-                average_fps=stream_dict.get("averageFps"),
+                average_fps_from_header=stream_dict.get("averageFps"),
                 stream_index=stream_index,
             )
         )

src/torchcodec/decoders/_simple_video_decoder.py

@@ -140,19 +140,23 @@ def __init__(
             )
         self._num_frames = self.metadata.num_frames_from_content
 
-        if self.metadata.min_pts_seconds is None:
+        if self.metadata.begin_stream_from_content_seconds is None:
             raise ValueError(
                 "The minimum pts value in seconds is unknown. "
                 + _ERROR_REPORTING_INSTRUCTIONS
             )
-        self._min_pts_seconds = self.metadata.min_pts_seconds
+        self._begin_stream_from_content_seconds = (
+            self.metadata.begin_stream_from_content_seconds
+        )
 
-        if self.metadata.max_pts_seconds is None:
+        if self.metadata.end_stream_from_content_seconds is None:
             raise ValueError(
                 "The maximum pts value in seconds is unknown. "
                 + _ERROR_REPORTING_INSTRUCTIONS
             )
-        self._max_pts_seconds = self.metadata.max_pts_seconds
+        self._end_stream_from_content_seconds = (
+            self.metadata.end_stream_from_content_seconds
+        )
 
     def __len__(self) -> int:
         return self._num_frames
@@ -270,11 +274,15 @@ def get_frame_displayed_at(self, seconds: float) -> Frame:
         Returns:
             Frame: The frame that is displayed at ``seconds``.
         """
-        if not self._min_pts_seconds <= seconds < self._max_pts_seconds:
+        if (
+            not self._begin_stream_from_content_seconds
+            <= seconds
+            < self._end_stream_from_content_seconds
+        ):
             raise IndexError(
                 f"Invalid pts in seconds: {seconds}. "
-                f"It must be greater than or equal to {self._min_pts_seconds} "
-                f"and less than or equal to {self._max_pts_seconds}."
+                f"It must be greater than or equal to {self._begin_stream_from_content_seconds} "
+                f"and less than {self._end_stream_from_content_seconds}."
             )
         data, pts_seconds, duration_seconds = core.get_frame_at_pts(
             self._decoder, seconds

test/decoders/test_metadata.py

@@ -88,16 +88,16 @@ def test_num_frames_fallback(
 ):
     """Check that num_frames_from_content always has priority when accessing `.num_frames`"""
     metadata = VideoStreamMetadata(
-        duration_seconds=4,
+        duration_seconds_from_header=4,
         bit_rate=123,
         num_frames_from_header=num_frames_from_header,
         num_frames_from_content=num_frames_from_content,
-        min_pts_seconds=0,
-        max_pts_seconds=4,
+        begin_stream_from_content_seconds=0,
+        end_stream_from_content_seconds=4,
         codec="whatever",
         width=123,
         height=321,
-        average_fps=30,
+        average_fps_from_header=30,
         stream_index=0,
     )
 

test/decoders/test_simple_video_decoder.py

@@ -37,6 +37,9 @@ def test_create(self, source_kind):
             == 390
         )
         assert decoder._stream_index == decoder.metadata.stream_index == 3
+        assert decoder.metadata.duration_seconds == pytest.approx(13.013)
+        assert decoder.metadata.average_fps == pytest.approx(29.970029)
+        assert decoder.metadata.num_frames == 390
 
     def test_create_fails(self):
         with pytest.raises(TypeError, match="Unknown source type"):