Narrow to the CLI, restoring the existing seek() behaviour

Issue #380 reports inconsistent CLI behaviour when the start time exceeds the
video length. The previous revision went further and made seek() raise
SeekError on every backend when the target was at or past duration.

That broke real callers: save_images seeks near the end of variable-frame-rate
video, where the backends report different nominal frame rates, so a rebased
scene position now raised instead of clamping. It also contradicted the note in
moviepy.py saying backends "should probably gracefully stop at the last frame
instead of throwing", which that revision deleted along with the test in
test_video_stream.py documenting the existing contract.

Reverts the seek() changes in all three backends and restores both the note and
the tests. What remains is the CLI-level rejection the issue asks for, plus a
guard for OpenCV 5 returning NaN from CAP_PROP_POS_FRAMES after a seek past EOF,
which crashed round() and hung the decode thread.

Author: cpruijsen

scenedetect/backends/moviepy.py

@@ -246,8 +246,6 @@ def seek(self, target: TimecodeLike):
             target = FrameTimecode(target, self.frame_rate)
         duration = self.duration
         assert duration is not None
-        if duration > 0 and target >= duration:
-            raise SeekError("Target frame is beyond end of video!")
         try:
             self._last_frame = _retry_on_oserror(
                 "seek", lambda: self._reader.get_frame(target.seconds)
@@ -260,6 +258,11 @@ def seek(self, target: TimecodeLike):
             )
             success = True
         except OSError as ex:
+            # TODO(https://scenedetect.com/issues/380): Other backends do not currently throw an
+            # exception if attempting to seek past EOF.
+            #
+            # We need to ensure consistency for seeking past end of video with respect to errors and
+            # behaviour, and should probably gracefully stop at the last frame instead of throwing.
             if target >= duration:
                 raise SeekError("Target frame is beyond end of video!") from ex
             raise

scenedetect/backends/opencv.py

@@ -250,9 +250,6 @@ def seek(self, target: TimecodeLike):
             target = FrameTimecode(target, self.frame_rate)
         if target < 0:
             raise ValueError("Target seek position cannot be negative!")
-        duration = self.duration
-        if duration is not None and duration > 0 and target >= duration:
-            raise SeekError("Target frame is beyond end of video!")
         target_secs = (self.base_timecode + target).seconds
         self._has_grabbed = False
         if target_secs > 0:

scenedetect/backends/pyav.py

@@ -29,7 +29,7 @@
     framerate_to_fraction,
 )
 from scenedetect.platform import StrPath, get_file_name
-from scenedetect.video_stream import FrameRateUnavailable, SeekError, VideoOpenFailure, VideoStream
+from scenedetect.video_stream import FrameRateUnavailable, VideoOpenFailure, VideoStream
 
 logger = getLogger("pyscenedetect")
 VALID_THREAD_MODES = ["NONE", "SLICE", "FRAME", "AUTO"]
@@ -286,15 +286,12 @@ def seek(self, target: TimecodeLike) -> None:
                 If float, interpreted as time in seconds.
                 If int, interpreted as frame number.
         Raises:
-            SeekError: An error occurs while seeking, or `target` is beyond the end of the video.
             ValueError: `target` is not a valid value (i.e. it is negative).
         """
         if not isinstance(target, FrameTimecode):
             target = FrameTimecode(target, self.frame_rate)
         if target < 0:
             raise ValueError("Target cannot be negative!")
-        if self.duration > 0 and target >= self.duration:
-            raise SeekError("Target frame is beyond end of video!")
         beginning = target == 0
 
         target = self.base_timecode + target

tests/test_backend_opencv.py

@@ -22,7 +22,6 @@
 
 from scenedetect import ContentDetector, SceneManager
 from scenedetect.backends.opencv import VideoCaptureAdapter, VideoStreamCv2
-from scenedetect.video_stream import SeekError
 
 GROUND_TRUTH_CAPTURE_ADAPTER_TEST = [1, 90, 210]
 GROUND_TRUTH_CAPTURE_ADAPTER_CALLBACK_TEST = [180, 394]
@@ -36,9 +35,7 @@ def test_open_image_sequence(test_image_sequence: str):
     assert sequence.duration is not None
     assert sequence.duration.frame_num == 30
     assert sequence.read() is not False
-    with pytest.raises(SeekError):
-        sequence.seek(100)
-    sequence.seek(sequence.duration.frame_num - 1)
+    sequence.seek(100)
     assert sequence.position == 29
 
 

tests/test_video_stream.py

@@ -318,9 +318,21 @@ def test_seek_past_eof(
     ):
         """Validate calling `seek()` to offset past end of video."""
         stream = auto_close(vs_type(test_video.path))
-        # All backends raise SeekError when the target is at or past duration (#380).
-        with pytest.raises(SeekError):
+        # Seek to a large seek offset past the end of the video. Some backends only support 32-bit
+        # frame numbers so that's our max offset. Certain backends disallow seek offsets past EOF,
+        # in which case they should raise a SeekError (and the test is considered a pass).
+        try:
             stream.seek(2**32)
+        except SeekError:
+            return
+        # For those backends that do allow seek offsets past EOF, they should act as though we
+        # seeked to the end of the video (i.e. shouldn't be able to decode any more frames).
+        assert stream.read() is False
+        # TODO: On some videos, the PyAV backend seems to drop a frame. See where this occurs.
+        if vs_type == VideoStreamAv:
+            assert stream.frame_number in (test_video.total_frames, test_video.total_frames - 1)
+        else:
+            assert stream.frame_number == test_video.total_frames
 
     def test_seek_invalid(
         self, vs_type: ty.Callable[..., VideoStream], test_video: VideoParameters, auto_close

website/pages/changelog.md

@@ -14,7 +14,6 @@ PySceneDetect 0.7.1 adds support for concatenating multiple videos, along with s
 
 #### API Changes
 
- - [bugfix] `VideoStream.seek()` now raises `SeekError` on every backend when the target is at or past the video duration [#380](https://github.com/Breakthrough/PySceneDetect/issues/380)
  - [feature] `scenedetect.detect()` now accepts a `backend` keyword argument (`"opencv"`, `"pyav"`, or `"moviepy"`) similar to `open_video`. Defaults to `"opencv"`, matching prior behavior.
  - [feature] Add `expand_scenes_to_bounds()` helper in `scenedetect.scene_manager` to extend a scene list so the first scene starts at a given lower bound and the last scene ends at a given upper bound
  - [feature] `VideoStream` now provides a public read-only `decode_failures` property reporting the number of frames that failed to decode and were skipped (defaults to 0; populated by the OpenCV and PyAV backends)