Update minPtsSecondsFromScan, maxPtsSecondsFromScan, numFramesFromScan

Author: Dan-Flores

src/torchcodec/_core/Metadata.h

@@ -37,10 +37,10 @@ struct StreamMetadata {
   std::optional<int64_t> minPtsFromScan;
   std::optional<int64_t> maxPtsFromScan;
   // These presentation timestamps are in seconds.
-  std::optional<double> minPtsSecondsFromScan;
-  std::optional<double> maxPtsSecondsFromScan;
+  std::optional<double> beginStreamSecondsFromContent;
+  std::optional<double> endStreamFromContentSeconds;
   // This can be useful for index-based seeking.
-  std::optional<int64_t> numFramesFromScan;
+  std::optional<int64_t> numFramesFromContent;
 
   // Video-only fields derived from the AVCodecContext.
   std::optional<int64_t> width;

src/torchcodec/_core/SingleStreamDecoder.cpp

@@ -241,8 +241,8 @@ void SingleStreamDecoder::scanFileAndUpdateMetadataAndIndex() {
     streamMetadata.maxPtsFromScan = std::max(
         streamMetadata.maxPtsFromScan.value_or(INT64_MIN),
         getPtsOrDts(packet) + packet->duration);
-    streamMetadata.numFramesFromScan =
-        streamMetadata.numFramesFromScan.value_or(0) + 1;
+    streamMetadata.numFramesFromContent =
+        streamMetadata.numFramesFromContent.value_or(0) + 1;
 
     // Note that we set the other value in this struct, nextPts, only after
     // we have scanned all packets and sorted by pts.
@@ -262,15 +262,15 @@ void SingleStreamDecoder::scanFileAndUpdateMetadataAndIndex() {
     auto& streamMetadata = containerMetadata_.allStreamMetadata[streamIndex];
     auto avStream = formatContext_->streams[streamIndex];
 
-    streamMetadata.numFramesFromScan =
+    streamMetadata.numFramesFromContent =
         streamInfos_[streamIndex].allFrames.size();
 
     if (streamMetadata.minPtsFromScan.has_value()) {
-      streamMetadata.minPtsSecondsFromScan =
+      streamMetadata.beginStreamSecondsFromContent =
           *streamMetadata.minPtsFromScan * av_q2d(avStream->time_base);
     }
     if (streamMetadata.maxPtsFromScan.has_value()) {
-      streamMetadata.maxPtsSecondsFromScan =
+      streamMetadata.endStreamFromContentSeconds =
           *streamMetadata.maxPtsFromScan * av_q2d(avStream->time_base);
     }
   }
@@ -1461,7 +1461,7 @@ int64_t SingleStreamDecoder::getNumFrames(
     const StreamMetadata& streamMetadata) {
   switch (seekMode_) {
     case SeekMode::exact:
-      return streamMetadata.numFramesFromScan.value();
+      return streamMetadata.numFramesFromContent.value();
     case SeekMode::approximate: {
       TORCH_CHECK(
           streamMetadata.numFramesFromHeader.has_value(),
@@ -1477,7 +1477,7 @@ double SingleStreamDecoder::getMinSeconds(
     const StreamMetadata& streamMetadata) {
   switch (seekMode_) {
     case SeekMode::exact:
-      return streamMetadata.minPtsSecondsFromScan.value();
+      return streamMetadata.beginStreamSecondsFromContent.value();
     case SeekMode::approximate:
       return 0;
     default:
@@ -1489,7 +1489,7 @@ double SingleStreamDecoder::getMaxSeconds(
     const StreamMetadata& streamMetadata) {
   switch (seekMode_) {
     case SeekMode::exact:
-      return streamMetadata.maxPtsSecondsFromScan.value();
+      return streamMetadata.endStreamFromContentSeconds.value();
     case SeekMode::approximate: {
       TORCH_CHECK(
           streamMetadata.durationSecondsFromHeader.has_value(),

src/torchcodec/_core/SingleStreamDecoder.h

@@ -121,7 +121,7 @@ class SingleStreamDecoder {
   //
   // Valid values for startSeconds and stopSeconds are:
   //
-  //   [minPtsSecondsFromScan, maxPtsSecondsFromScan)
+  //   [beginStreamSecondsFromContent, maxPtsSecondsFromScan)
   FrameBatchOutput getFramesPlayedInRange(
       double startSeconds,
       double stopSeconds);

src/torchcodec/_core/_metadata.py

@@ -227,23 +227,25 @@ def get_container_metadata(decoder: torch.Tensor) -> ContainerMetadata:
         common_meta = dict(
             duration_seconds_from_header=stream_dict.get("durationSecondsFromHeader"),
             bit_rate=stream_dict.get("bitRate"),
-            begin_stream_seconds_from_header=stream_dict.get("beginStreamSecondsFromHeader"),
+            begin_stream_seconds_from_header=stream_dict.get(
+                "beginStreamSecondsFromHeader"
+            ),
             codec=stream_dict.get("codec"),
             stream_index=stream_index,
         )
         if stream_dict["mediaType"] == "video":
             streams_metadata.append(
                 VideoStreamMetadata(
                     begin_stream_seconds_from_content=stream_dict.get(
-                        "minPtsSecondsFromScan"
+                        "beginStreamSecondsFromContent"
                     ),
                     end_stream_seconds_from_content=stream_dict.get(
-                        "maxPtsSecondsFromScan"
+                        "endStreamFromContentSeconds"
                     ),
                     width=stream_dict.get("width"),
                     height=stream_dict.get("height"),
                     num_frames_from_header=stream_dict.get("numFramesFromHeader"),
-                    num_frames_from_content=stream_dict.get("numFramesFromScan"),
+                    num_frames_from_content=stream_dict.get("numFramesFromContent"),
                     average_fps_from_header=stream_dict.get("averageFpsFromHeader"),
                     **common_meta,
                 )

src/torchcodec/_core/custom_ops.cpp

@@ -478,20 +478,20 @@ std::string get_json_metadata(at::Tensor& decoder) {
   if (maybeBestVideoStreamIndex.has_value()) {
     auto streamMetadata =
         videoMetadata.allStreamMetadata[*maybeBestVideoStreamIndex];
-    if (streamMetadata.numFramesFromScan.has_value()) {
+    if (streamMetadata.numFramesFromContent.has_value()) {
       metadataMap["numFramesFromHeader"] =
-          std::to_string(*streamMetadata.numFramesFromScan);
+          std::to_string(*streamMetadata.numFramesFromContent);
     } else if (streamMetadata.numFramesFromHeader.has_value()) {
       metadataMap["numFramesFromHeader"] =
           std::to_string(*streamMetadata.numFramesFromHeader);
     }
-    if (streamMetadata.minPtsSecondsFromScan.has_value()) {
-      metadataMap["minPtsSecondsFromScan"] =
-          std::to_string(*streamMetadata.minPtsSecondsFromScan);
+    if (streamMetadata.beginStreamSecondsFromContent.has_value()) {
+      metadataMap["beginStreamSecondsFromContent"] =
+          std::to_string(*streamMetadata.beginStreamSecondsFromContent);
     }
-    if (streamMetadata.maxPtsSecondsFromScan.has_value()) {
-      metadataMap["maxPtsSecondsFromScan"] =
-          std::to_string(*streamMetadata.maxPtsSecondsFromScan);
+    if (streamMetadata.endStreamFromContentSeconds.has_value()) {
+      metadataMap["endStreamFromContentSeconds"] =
+          std::to_string(*streamMetadata.endStreamFromContentSeconds);
     }
     if (streamMetadata.codecName.has_value()) {
       metadataMap["codec"] = quoteValue(streamMetadata.codecName.value());
@@ -574,9 +574,9 @@ std::string get_stream_json_metadata(
   if (streamMetadata.bitRate.has_value()) {
     map["bitRate"] = std::to_string(*streamMetadata.bitRate);
   }
-  if (streamMetadata.numFramesFromScan.has_value()) {
-    map["numFramesFromScan"] =
-        std::to_string(*streamMetadata.numFramesFromScan);
+  if (streamMetadata.numFramesFromContent.has_value()) {
+    map["numFramesFromContent"] =
+        std::to_string(*streamMetadata.numFramesFromContent);
   }
   if (streamMetadata.numFramesFromHeader.has_value()) {
     map["numFramesFromHeader"] =
@@ -586,13 +586,13 @@ std::string get_stream_json_metadata(
     map["beginStreamSecondsFromHeader"] =
         std::to_string(*streamMetadata.beginStreamSecondsFromHeader);
   }
-  if (streamMetadata.minPtsSecondsFromScan.has_value()) {
-    map["minPtsSecondsFromScan"] =
-        std::to_string(*streamMetadata.minPtsSecondsFromScan);
+  if (streamMetadata.beginStreamSecondsFromContent.has_value()) {
+    map["beginStreamSecondsFromContent"] =
+        std::to_string(*streamMetadata.beginStreamSecondsFromContent);
   }
-  if (streamMetadata.maxPtsSecondsFromScan.has_value()) {
-    map["maxPtsSecondsFromScan"] =
-        std::to_string(*streamMetadata.maxPtsSecondsFromScan);
+  if (streamMetadata.endStreamFromContentSeconds.has_value()) {
+    map["endStreamFromContentSeconds"] =
+        std::to_string(*streamMetadata.endStreamFromContentSeconds);
   }
   if (streamMetadata.codecName.has_value()) {
     map["codec"] = quoteValue(streamMetadata.codecName.value());

src/torchcodec/_samplers/video_clip_sampler.py

@@ -271,18 +271,18 @@ def _get_start_seconds(
             + 1
         ) / metadata_json["averageFpsFromHeader"]
 
-        minPtsSecondsFromScan = (
-            metadata_json["minPtsSecondsFromScan"]
-            if metadata_json["minPtsSecondsFromScan"]
+        beginStreamSecondsFromContent = (
+            metadata_json["beginStreamSecondsFromContent"]
+            if metadata_json["beginStreamSecondsFromContent"]
             else 0
         )
-        maxPtsSecondsFromScan = (
-            metadata_json["maxPtsSecondsFromScan"]
-            if metadata_json["maxPtsSecondsFromScan"] > 0
+        endStreamFromContentSeconds = (
+            metadata_json["endStreamFromContentSeconds"]
+            if metadata_json["endStreamFromContentSeconds"] > 0
             else video_duration_in_seconds
         )
         last_possible_clip_start_in_seconds = (
-            maxPtsSecondsFromScan - clip_duration_in_seconds
+            endStreamFromContentSeconds - clip_duration_in_seconds
         )
         if last_possible_clip_start_in_seconds < 0:
             raise VideoTooShortException(
@@ -292,7 +292,7 @@ def _get_start_seconds(
         clip_starts_in_seconds: List[float] = []
         sample_start_second = max(
             time_based_sampler_args.sample_start_second,
-            minPtsSecondsFromScan,
+            beginStreamSecondsFromContent,
         )
         sample_end_second = min(
             last_possible_clip_start_in_seconds,

test/VideoDecoderTest.cpp

@@ -84,15 +84,15 @@ TEST_P(SingleStreamDecoderTest, ReturnsFpsAndDurationForVideoInMetadata) {
   EXPECT_NEAR(*videoStream.bitRate, 128783, 1e-1);
   EXPECT_NEAR(*videoStream.durationSeconds, 13.013, 1e-1);
   EXPECT_EQ(videoStream.numFrames, 390);
-  EXPECT_FALSE(videoStream.minPtsSecondsFromScan.has_value());
-  EXPECT_FALSE(videoStream.maxPtsSecondsFromScan.has_value());
-  EXPECT_FALSE(videoStream.numFramesFromScan.has_value());
+  EXPECT_FALSE(videoStream.beginStreamSecondsFromContent.has_value());
+  EXPECT_FALSE(videoStream.endStreamFromContentSeconds.has_value());
+  EXPECT_FALSE(videoStream.numFramesFromContent.has_value());
   decoder->scanFileAndUpdateMetadataAndIndex();
   metadata = decoder->getContainerMetadata();
   const auto& videoStream1 = metadata.allStreamMetadata[3];
-  EXPECT_EQ(*videoStream1.minPtsSecondsFromScan, 0);
-  EXPECT_EQ(*videoStream1.maxPtsSecondsFromScan, 13.013);
-  EXPECT_EQ(*videoStream1.numFramesFromScan, 390);
+  EXPECT_EQ(*videoStream1.beginStreamSecondsFromContent, 0);
+  EXPECT_EQ(*videoStream1.endStreamFromContentSeconds, 13.013);
+  EXPECT_EQ(*videoStream1.numFramesFromContent, 390);
 }
 
 TEST(SingleStreamDecoderTest, MissingVideoFileThrowsException) {

test/test_ops.py

@@ -414,8 +414,8 @@ def test_video_get_json_metadata_with_stream(self):
         metadata_dict = json.loads(metadata)
         assert metadata_dict["width"] == 480
         assert metadata_dict["height"] == 270
-        assert metadata_dict["minPtsSecondsFromScan"] == 0
-        assert metadata_dict["maxPtsSecondsFromScan"] == 13.013
+        assert metadata_dict["beginStreamSecondsFromContent"] == 0
+        assert metadata_dict["endStreamFromContentSeconds"] == 13.013
 
     def test_get_ffmpeg_version(self):
         ffmpeg_dict = get_ffmpeg_library_versions()