[common] Add TimecodeLike type hint

Author: Breakthrough

scenedetect/__init__.py

@@ -37,6 +37,7 @@
     CutList,
     CropRegion,
     TimecodePair,
+    TimecodeLike,
     Interpolation,
 )
 from scenedetect.video_stream import VideoStream, VideoOpenFailure
@@ -136,8 +137,8 @@ def detect(
     detector: SceneDetector,
     stats_file_path: str | None = None,
     show_progress: bool = False,
-    start_time: str | float | int | None = None,
-    end_time: str | float | int | None = None,
+    start_time: TimecodeLike | None = None,
+    end_time: TimecodeLike | None = None,
     start_in_scene: bool = False,
 ) -> SceneList:
     """Perform scene detection on a given video `path` using the specified `detector`.
@@ -170,18 +171,16 @@ def detect(
     """
     video = open_video(video_path)
     if start_time is not None:
-        start_time = video.base_timecode + start_time
-        video.seek(start_time)
-    if end_time is not None:
-        end_time = video.base_timecode + end_time
+        video.seek(FrameTimecode(start_time, video.frame_rate))
+    end_timecode = FrameTimecode(end_time, video.frame_rate) if end_time is not None else None
     # To reduce memory consumption when not required, we only add a StatsManager if we
     # need to save frame metrics to disk.
     scene_manager = SceneManager(StatsManager() if stats_file_path else None)
     scene_manager.add_detector(detector)
     scene_manager.detect_scenes(
         video=video,
         show_progress=show_progress,
-        end_time=end_time,
+        end_time=end_timecode,
     )
     if scene_manager.stats_manager is not None:
         scene_manager.stats_manager.save_to_csv(csv_file=stats_file_path)

scenedetect/backends/moviepy.py

@@ -26,7 +26,7 @@
 from moviepy.video.io.ffmpeg_reader import FFMPEG_VideoReader
 
 from scenedetect.backends.opencv import VideoStreamCv2
-from scenedetect.common import FrameTimecode, Timecode, framerate_to_fraction
+from scenedetect.common import FrameTimecode, Timecode, TimecodeLike, framerate_to_fraction
 from scenedetect.platform import get_file_name
 from scenedetect.video_stream import SeekError, VideoOpenFailure, VideoStream
 
@@ -189,7 +189,7 @@ def frame_number(self) -> int:
         """
         return self._frame_number
 
-    def seek(self, target: FrameTimecode | float | int):
+    def seek(self, target: TimecodeLike):
         """Seek to the given timecode. If given as a frame number, represents the current seek
         pointer (e.g. if seeking to 0, the next frame decoded will be the first frame of the video).
 

scenedetect/backends/opencv.py

@@ -27,7 +27,13 @@
 import cv2
 import numpy as np
 
-from scenedetect.common import MAX_FPS_DELTA, FrameTimecode, Timecode, framerate_to_fraction
+from scenedetect.common import (
+    MAX_FPS_DELTA,
+    FrameTimecode,
+    Timecode,
+    TimecodeLike,
+    framerate_to_fraction,
+)
 from scenedetect.platform import get_file_name
 from scenedetect.video_stream import (
     FrameRateUnavailable,
@@ -231,9 +237,11 @@ def frame_number(self) -> int:
         assert self._cap is not None
         return math.trunc(self._cap.get(cv2.CAP_PROP_POS_FRAMES))
 
-    def seek(self, target: FrameTimecode | float | int):
+    def seek(self, target: TimecodeLike):
         if self._is_device:
             raise SeekError("Cannot seek if input is a device!")
+        if not isinstance(target, FrameTimecode):
+            target = FrameTimecode(target, self.frame_rate)
         if target < 0:
             raise ValueError("Target seek position cannot be negative!")
         assert self._cap is not None
@@ -484,7 +492,7 @@ def position_ms(self) -> float:
     def frame_number(self) -> int:
         return self._num_frames
 
-    def seek(self, target: FrameTimecode | float | int):
+    def seek(self, target: TimecodeLike):
         """The underlying VideoCapture is assumed to not support seeking."""
         raise NotImplementedError("Seeking is not supported.")
 

scenedetect/backends/pyav.py

@@ -18,7 +18,7 @@
 import av
 import numpy as np
 
-from scenedetect.common import MAX_FPS_DELTA, FrameTimecode, Timecode
+from scenedetect.common import MAX_FPS_DELTA, FrameTimecode, Timecode, TimecodeLike
 from scenedetect.platform import get_file_name
 from scenedetect.video_stream import FrameRateUnavailable, VideoOpenFailure, VideoStream
 
@@ -234,7 +234,7 @@ def aspect_ratio(self) -> float:
         frame_aspect_ratio = self.frame_size[0] / self.frame_size[1]
         return display_aspect_ratio / frame_aspect_ratio
 
-    def seek(self, target: FrameTimecode | float | int) -> None:
+    def seek(self, target: TimecodeLike) -> None:
         """Seek to the given timecode. If given as a frame number, represents the current seek
         pointer (e.g. if seeking to 0, the next frame decoded will be the first frame of the video).
 
@@ -252,6 +252,8 @@ def seek(self, target: FrameTimecode | float | int) -> None:
         Raises:
             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!")
         beginning = target == 0

scenedetect/common.py

@@ -715,3 +715,10 @@ def _get_other_as_seconds(self, other: ty.Union[int, float, str, "FrameTimecode"
 
 def _compare_as_fixed(a: FrameTimecode, b: ty.Any) -> bool:
     return a._rate is not None and isinstance(b, FrameTimecode) and b._rate is not None
+
+
+TimecodeLike = int | float | str | Timecode | FrameTimecode
+"""Type hint for values that can be converted to a :class:`FrameTimecode`. Accepts a frame number
+(`int`), number of seconds (`float`), timecode string (`str` of the form ``HH:MM:SS[.nnn]``), a
+:class:`Timecode`, or an existing :class:`FrameTimecode`.
+"""

scenedetect/video_stream.py

@@ -36,7 +36,7 @@
 
 import numpy as np
 
-from scenedetect.common import FrameTimecode
+from scenedetect.common import FrameTimecode, TimecodeLike
 
 
 class SeekError(Exception):
@@ -193,7 +193,7 @@ def reset(self) -> None:
         ...
 
     @abstractmethod
-    def seek(self, target: FrameTimecode | float | int) -> None:
+    def seek(self, target: TimecodeLike) -> None:
         """Seek to the given timecode. If given as a frame number, represents the current seek
         pointer (e.g. if seeking to 0, the next frame decoded will be the first frame of the video).