[backends] Allow concatenating multiple inputs

Also fix a few normalization issues for videos that don't start at time 0.

Author: Breakthrough

docs/api.rst

@@ -35,6 +35,8 @@ The `scenedetect` API is easy to integrate with most application workflows, whil
 
         * MoviePy: :class:`VideoStreamMoviePy <scenedetect.backends.moviepy.VideoStreamMoviePy>`
 
+        * Multiple videos can be treated as a single continuous stream using :class:`VideoStreamConcat <scenedetect.backends.concat.VideoStreamConcat>` (e.g. ``open_video(["part1.mp4", "part2.mp4"])``)
+
     * :ref:`scenedetect.common ⏱️ <scenedetect-common>`: common functionality such as :class:`FrameTimecode <scenedetect.common.FrameTimecode>` for timecode handling
 
     * :ref:`scenedetect.scene_manager 🎞️ <scenedetect-scene_manager>`: the :class:`SceneManager <scenedetect.scene_manager.SceneManager>` coordinates performing scene detection on a video with one or more detectors

docs/api/backends.rst

@@ -16,3 +16,6 @@ Video Backends
 
 .. automodule:: scenedetect.backends.moviepy
    :members:
+
+.. automodule:: scenedetect.backends.concat
+   :members:

scenedetect/__init__.py

@@ -69,6 +69,8 @@
     VideoStreamAv,
     VideoStreamMoviePy,
     VideoCaptureAdapter,
+    VideoStreamConcat,
+    SourceSpan,
 )
 from scenedetect.stats_manager import StatsManager, StatsFileCorrupt
 from scenedetect.scene_manager import SceneManager
@@ -82,7 +84,7 @@
 
 
 def open_video(
-    path: StrPath,
+    path: "StrPath | list[StrPath] | tuple[StrPath, ...]",
     frame_rate: FrameRate | None = None,
     backend: str = "opencv",
     framerate: float | None = None,
@@ -92,7 +94,9 @@ def open_video(
     system, OpenCV (`VideoStreamCv2`) will be used as a fallback.
 
     Arguments:
-        path: Path to video file to open.
+        path: Path to video file to open. May also be a list of paths, in which case the videos
+            are concatenated and treated as a single continuous stream
+            (see :class:`VideoStreamConcat <scenedetect.backends.concat.VideoStreamConcat>`).
         frame_rate: Overrides detected frame rate if set. Takes precedence over `framerate`.
         backend: Name of specific backend to use, if possible. See
             :data:`scenedetect.backends.AVAILABLE_BACKENDS` for backends available on the current
@@ -113,6 +117,10 @@ def open_video(
     # used, once internal callers and downstream users have had a release to migrate.
     if frame_rate is None:
         frame_rate = framerate
+    # A list of paths is opened as a single concatenated stream. VideoStreamConcat handles
+    # backend selection/fallback internally, so this must come before the lookup below.
+    if isinstance(path, (list, tuple)):
+        return VideoStreamConcat(path, frame_rate, backend=backend, **kwargs)
     last_error: Exception | None = None
     # If `backend` is available, try to open the video at `path` using it.
     if backend in AVAILABLE_BACKENDS:
@@ -142,7 +150,7 @@ def open_video(
 
 
 def detect(
-    video_path: StrPath,
+    video_path: "StrPath | list[StrPath] | tuple[StrPath, ...]",
     detector: SceneDetector,
     stats_file_path: StrPath | None = None,
     show_progress: bool = False,
@@ -154,7 +162,9 @@ def detect(
     """Perform scene detection on a given video `path` using the specified `detector`.
 
     Arguments:
-        video_path: Path to input video (absolute or relative to working directory).
+        video_path: Path to input video (absolute or relative to working directory). May also
+            be a list of paths, in which case the videos are concatenated and treated as a
+            single continuous stream.
         detector: A `SceneDetector` instance (see :mod:`scenedetect.detectors` for a full list
             of detectors).
         stats_file_path: Path to save per-frame metrics to for statistical analysis or to

scenedetect/backends/__init__.py

@@ -50,6 +50,14 @@
 In both examples above, the resulting ``video`` can be used with
 :meth:`SceneManager.detect_scenes() <scenedetect.scene_manager.SceneManager.detect_scenes>`.
 
+Multiple videos can be opened as one continuous stream by passing a list of paths to
+:func:`open_video`, which returns a
+:class:`VideoStreamConcat <scenedetect.backends.concat.VideoStreamConcat>`:
+
+.. code:: python
+
+    video = open_video(["part1.mp4", "part2.mp4"])
+
 ===============================================================
 Devices / Cameras / Pipes
 ===============================================================
@@ -84,6 +92,7 @@
 #  - Nvidia VPF: https://developer.nvidia.com/blog/vpf-hardware-accelerated-video-processing-framework-in-python/
 
 # OpenCV must be available at minimum.
+from scenedetect.backends.concat import SourceSpan, VideoStreamConcat
 from scenedetect.backends.opencv import VideoCaptureAdapter, VideoStreamCv2
 
 try: