[api] Convert frame-based defaults to temporal values (#531)

Replace frame-based defaults with temporal (time-based) values to properly
support VFR video. Rename save-images --frame-margin to --margin (default
0.1s), and change min_scene_len default from 15 frames to "0.6s" across all
detectors. FlashFilter now accepts temporal values directly. Deprecated
options still work with warnings.

Author: Breakthrough

docs/cli.rst

@@ -658,11 +658,11 @@ Options
 
   Default: ``3``
 
-.. option:: -m N, --frame-margin N
+.. option:: -m TIMECODE, --margin TIMECODE
 
-  Number of frames to ignore at beginning/end of scenes when saving images. Controls temporal padding on scene boundaries.
+  Margin from scene boundary for first/last image. Accepts time (``0.1s``), frames (``3``), or timecode (``00:00:00.100``).
 
-  Default: ``3``
+  Default: ``0.1s``
 
 .. option:: -s S, --scale S
 

scenedetect.cfg

@@ -227,8 +227,9 @@
 # Compression amount for png images (0 to 9). Only affects size, not quality.
 #compression = 3
 
-# Number of frames to ignore around each scene cut when selecting frames.
-#frame-margin = 1
+# Margin from scene boundary for first/last image. Accepts time (0.1s),
+# frames (3), or timecode (00:00:00.100).
+#margin = 0.1s
 
 # Resize by scale factor (0.5 = half, 1.0 = same, 2.0 = double).
 #scale = 1.0

scenedetect/__init__.py

@@ -53,7 +53,7 @@
     VideoMetadata,
     SceneMetadata,
 )
-from scenedetect.detector import SceneDetector
+from scenedetect.detector import DEFAULT_MIN_SCENE_LEN, SceneDetector
 from scenedetect.detectors import (
     ContentDetector,
     AdaptiveDetector,

scenedetect/_cli/__init__.py

@@ -1396,12 +1396,18 @@ def split_video_command(
 )
 @click.option(
     "-m",
+    "--margin",
+    metavar="DURATION",
+    default=None,
+    type=click.STRING,
+    help="Margin from scene boundary for first/last image. Accepts duration (0.1s), frame count (3), or HH:MM:SS.mmm format.%s"
+    % (USER_CONFIG.get_help_string("save-images", "margin")),
+)
+@click.option(
     "--frame-margin",
-    metavar="N",
     default=None,
-    type=click.INT,
-    help="Number of frames to ignore at beginning/end of scenes when saving images. Controls temporal padding on scene boundaries.%s"
-    % (USER_CONFIG.get_help_string("save-images", "num-images")),
+    type=click.STRING,
+    hidden=True,
 )
 @click.option(
     "--scale",
@@ -1441,7 +1447,8 @@ def save_images_command(
     quality: ty.Optional[int] = None,
     png: bool = False,
     compression: ty.Optional[int] = None,
-    frame_margin: ty.Optional[int] = None,
+    margin: ty.Optional[str] = None,
+    frame_margin: ty.Optional[str] = None,
     scale: ty.Optional[float] = None,
     height: ty.Optional[int] = None,
     width: ty.Optional[int] = None,
@@ -1487,9 +1494,13 @@ def save_images_command(
         raise click.BadParameter("\n".join(error_strs), param_hint="save-images")
     output = ctx.config.get_value("save-images", "output", output)
 
+    if frame_margin is not None and margin is None:
+        logger.warning("--frame-margin is deprecated, use --margin instead.")
+        margin = frame_margin
+
     save_images_args = {
         "encoder_param": compression if png else quality,
-        "frame_margin": ctx.config.get_value("save-images", "frame-margin", frame_margin),
+        "margin": ctx.config.get_value("save-images", "margin", margin),
         "height": height,
         "image_extension": image_extension,
         "filename": ctx.config.get_value("save-images", "filename", filename),

scenedetect/_cli/commands.py

@@ -180,7 +180,7 @@ def save_images(
     scenes: SceneList,
     cuts: CutList,
     num_images: int,
-    frame_margin: int,
+    margin: ty.Union[int, float, str],
     image_extension: str,
     encoder_param: int,
     filename: str,
@@ -199,7 +199,7 @@ def save_images(
         scene_list=scenes,
         video=context.video_stream,
         num_images=num_images,
-        frame_margin=frame_margin,
+        margin=margin,
         image_extension=image_extension,
         encoder_param=encoder_param,
         image_name_template=filename,

scenedetect/_cli/config.py

@@ -412,7 +412,7 @@ class XmlFormat(Enum):
         "compression": RangeValue(3, min_val=0, max_val=9),
         "filename": "$VIDEO_NAME-Scene-$SCENE_NUMBER-$IMAGE_NUMBER",
         "format": "jpeg",
-        "frame-margin": 1,
+        "margin": TimecodeValue("0.1s"),
         "height": 0,
         "num-images": 3,
         "output": None,
@@ -504,6 +504,12 @@ class XmlFormat(Enum):
 DEPRECATED_COMMANDS: ty.Dict[str, str] = {"export-html": "save-html"}
 """Deprecated config file sections that have a 1:1 mapping to a new replacement."""
 
+DEPRECATED_OPTIONS: ty.Dict[ty.Tuple[str, str], str] = {
+    ("save-images", "frame-margin"): "margin",
+}
+"""Deprecated config file options that have a 1:1 mapping to a new replacement.
+Keys are (section, old_option) tuples, values are the new option name."""
+
 
 def _validate_structure(parser: ConfigParser) -> ty.Tuple[bool, ty.List[LogMessage]]:
     """Validates the layout of the section/option mapping. Returns a bool indicating if validation
@@ -538,7 +544,16 @@ def _validate_structure(parser: ConfigParser) -> ty.Tuple[bool, ty.List[LogMessa
             logs.append((logging.ERROR, f"Unsupported config section: [{section_name}]"))
             continue
         for option_name, _ in parser.items(section_name):
-            if option_name not in CONFIG_MAP[section].keys():
+            if (section, option_name) in DEPRECATED_OPTIONS:
+                new_option = DEPRECATED_OPTIONS[(section, option_name)]
+                logs.append(
+                    (
+                        logging.WARNING,
+                        f"[{section_name}] option `{option_name}` is deprecated,"
+                        f" use `{new_option}` instead.",
+                    )
+                )
+            elif option_name not in CONFIG_MAP[section].keys():
                 success = False
                 logs.append(
                     (
@@ -564,6 +579,13 @@ def _parse_config(parser: ConfigParser) -> ty.Tuple[ty.Optional[ConfigDict], ty.
             replacement = DEPRECATED_COMMANDS[deprecated_command]
             parser[replacement] = parser[deprecated_command]
             del parser[deprecated_command]
+    # Re-map deprecated options to their replacements. Only remap when the new option is not
+    # already explicitly set (the explicit value should take precedence).
+    for (section, old_option), new_option in DEPRECATED_OPTIONS.items():
+        if section in parser and old_option in parser[section]:
+            if new_option not in parser[section]:
+                parser[section][new_option] = parser[section][old_option]
+            parser.remove_option(section, old_option)
     for command in CONFIG_MAP:
         config[command] = {}
         for option in CONFIG_MAP[command]:

scenedetect/_cli/context.py

@@ -314,7 +314,7 @@ def get_detect_content_params(
         self,
         threshold: ty.Optional[float] = None,
         luma_only: bool = None,
-        min_scene_len: ty.Optional[str] = None,
+        min_scene_len: ty.Optional[ty.Union[int, float, str]] = None,
         weights: ty.Optional[ty.Tuple[float, float, float, float]] = None,
         kernel_size: ty.Optional[int] = None,
         filter_mode: ty.Optional[str] = None,
@@ -325,10 +325,9 @@ def get_detect_content_params(
         else:
             if min_scene_len is None:
                 if self.config.is_default("detect-content", "min-scene-len"):
-                    min_scene_len = self.min_scene_len.frame_num
+                    min_scene_len = self.min_scene_len.seconds
                 else:
                     min_scene_len = self.config.get_value("detect-content", "min-scene-len")
-            min_scene_len = self.parse_timecode(min_scene_len).frame_num
 
         if weights is not None:
             try:
@@ -354,7 +353,7 @@ def get_detect_adaptive_params(
         min_content_val: ty.Optional[float] = None,
         frame_window: ty.Optional[int] = None,
         luma_only: bool = None,
-        min_scene_len: ty.Optional[str] = None,
+        min_scene_len: ty.Optional[ty.Union[int, float, str]] = None,
         weights: ty.Optional[ty.Tuple[float, float, float, float]] = None,
         kernel_size: ty.Optional[int] = None,
     ) -> ty.Dict[str, ty.Any]:
@@ -365,10 +364,9 @@ def get_detect_adaptive_params(
         else:
             if min_scene_len is None:
                 if self.config.is_default("detect-adaptive", "min-scene-len"):
-                    min_scene_len = self.min_scene_len.frame_num
+                    min_scene_len = self.min_scene_len.seconds
                 else:
                     min_scene_len = self.config.get_value("detect-adaptive", "min-scene-len")
-            min_scene_len = self.parse_timecode(min_scene_len).frame_num
 
         if weights is not None:
             try:
@@ -395,7 +393,7 @@ def get_detect_threshold_params(
         threshold: ty.Optional[float] = None,
         fade_bias: ty.Optional[float] = None,
         add_last_scene: bool = None,
-        min_scene_len: ty.Optional[str] = None,
+        min_scene_len: ty.Optional[ty.Union[int, float, str]] = None,
     ) -> ty.Dict[str, ty.Any]:
         """Handle detect-threshold command options and return args to construct one with."""
 
@@ -404,10 +402,9 @@ def get_detect_threshold_params(
         else:
             if min_scene_len is None:
                 if self.config.is_default("detect-threshold", "min-scene-len"):
-                    min_scene_len = self.min_scene_len.frame_num
+                    min_scene_len = self.min_scene_len.seconds
                 else:
                     min_scene_len = self.config.get_value("detect-threshold", "min-scene-len")
-            min_scene_len = self.parse_timecode(min_scene_len).frame_num
         # TODO(v1.0): add_last_scene cannot be disabled right now.
         return {
             "add_final_scene": add_last_scene
@@ -421,7 +418,7 @@ def get_detect_hist_params(
         self,
         threshold: ty.Optional[float] = None,
         bins: ty.Optional[int] = None,
-        min_scene_len: ty.Optional[str] = None,
+        min_scene_len: ty.Optional[ty.Union[int, float, str]] = None,
     ) -> ty.Dict[str, ty.Any]:
         """Handle detect-hist command options and return args to construct one with."""
 
@@ -430,10 +427,9 @@ def get_detect_hist_params(
         else:
             if min_scene_len is None:
                 if self.config.is_default("detect-hist", "min-scene-len"):
-                    min_scene_len = self.min_scene_len.frame_num
+                    min_scene_len = self.min_scene_len.seconds
                 else:
                     min_scene_len = self.config.get_value("detect-hist", "min-scene-len")
-            min_scene_len = self.parse_timecode(min_scene_len).frame_num
         return {
             "bins": self.config.get_value("detect-hist", "bins", bins),
             "min_scene_len": min_scene_len,
@@ -445,7 +441,7 @@ def get_detect_hash_params(
         threshold: ty.Optional[float] = None,
         size: ty.Optional[int] = None,
         lowpass: ty.Optional[int] = None,
-        min_scene_len: ty.Optional[str] = None,
+        min_scene_len: ty.Optional[ty.Union[int, float, str]] = None,
     ) -> ty.Dict[str, ty.Any]:
         """Handle detect-hash command options and return args to construct one with."""
 
@@ -454,10 +450,9 @@ def get_detect_hash_params(
         else:
             if min_scene_len is None:
                 if self.config.is_default("detect-hash", "min-scene-len"):
-                    min_scene_len = self.min_scene_len.frame_num
+                    min_scene_len = self.min_scene_len.seconds
                 else:
                     min_scene_len = self.config.get_value("detect-hash", "min-scene-len")
-            min_scene_len = self.parse_timecode(min_scene_len).frame_num
         return {
             "lowpass": self.config.get_value("detect-hash", "lowpass", lowpass),
             "min_scene_len": min_scene_len,

scenedetect/detector.py

@@ -24,6 +24,7 @@
     event (in, out, cut, etc...).
 """
 
+import math
 import typing as ty
 from abc import ABC, abstractmethod
 from enum import Enum
@@ -33,6 +34,9 @@
 from scenedetect.common import FrameTimecode
 from scenedetect.stats_manager import StatsManager
 
+DEFAULT_MIN_SCENE_LEN = "0.6s"
+"""Default minimum scene length for all detectors."""
+
 
 class SceneDetector(ABC):
     """Base class to inherit from when implementing a scene detection algorithm.
@@ -114,26 +118,50 @@ class Mode(Enum):
         SUPPRESS = 1
         """Suppress consecutive cuts until the filter length has passed."""
 
-    def __init__(self, mode: Mode, length: int):
+    def __init__(self, mode: Mode, length: ty.Union[int, float, str]):
         """
         Arguments:
             mode: The mode to use when enforcing `length`.
-            length: Number of frames to use when filtering cuts.
+            length: Minimum scene length. Can be an int (number of frames), float (seconds),
+                or str (e.g. ``"0.6s"``, ``"00:00:00.600"``).
         """
         self._mode = mode
-        self._filter_length = length  # Number of frames to use for activating the filter.
-        self._filter_secs: ty.Optional[float] = None  # Threshold in seconds, computed on first use.
+        self._filter_length = length
+        # Threshold in seconds. Set immediately for temporal values, or computed on first use
+        # from the video framerate for frame-based (int) values.
+        self._filter_secs: ty.Optional[float] = None
+        if isinstance(length, float):
+            self._filter_secs = length
+        elif isinstance(length, str) and not length.strip().isdigit():
+            # Temporal string like "0.6s" or "00:00:00.600" - parse to seconds immediately.
+            self._filter_secs = FrameTimecode(timecode=length, fps=100.0).seconds
+        elif isinstance(length, str):
+            # Digit-only string - treat as frame count, defer until we know the framerate.
+            self._filter_length = int(length)
         self._last_above = None  # Last frame above threshold.
         self._merge_enabled = False  # Used to disable merging until at least one cut was found.
         self._merge_triggered = False  # True when the merge filter is active.
         self._merge_start = None  # Frame number where we started the merge filter.
 
     @property
     def max_behind(self) -> int:
-        return 0 if self._mode == FlashFilter.Mode.SUPPRESS else self._filter_length
+        if self._mode == FlashFilter.Mode.SUPPRESS:
+            return 0
+        if isinstance(self._filter_length, int):
+            return self._filter_length
+        # For temporal values, estimate using a conservative high framerate to ensure the event
+        # buffer is large enough. ceil(seconds * 240fps) covers up to 240fps video.
+        return math.ceil(self._filter_secs * 240.0) if self._filter_secs else 0
+
+    @property
+    def _is_disabled(self) -> bool:
+        """Filter is disabled when length is zero."""
+        if self._filter_secs is not None:
+            return self._filter_secs <= 0.0
+        return self._filter_length <= 0
 
     def filter(self, timecode: FrameTimecode, above_threshold: bool) -> ty.List[FrameTimecode]:
-        if not self._filter_length > 0:
+        if self._is_disabled:
             return [timecode] if above_threshold else []
         if self._last_above is None:
             self._last_above = timecode

scenedetect/detectors/adaptive_detector.py

@@ -22,6 +22,7 @@
 import numpy as np
 
 from scenedetect.common import FrameTimecode
+from scenedetect.detector import DEFAULT_MIN_SCENE_LEN
 from scenedetect.detectors import ContentDetector
 
 logger = getLogger("pyscenedetect")
@@ -38,7 +39,7 @@ class AdaptiveDetector(ContentDetector):
     def __init__(
         self,
         adaptive_threshold: float = 3.0,
-        min_scene_len: int = 15,
+        min_scene_len: ty.Union[int, float, str] = DEFAULT_MIN_SCENE_LEN,
         window_width: int = 2,
         min_content_val: float = 15.0,
         weights: ContentDetector.Components = ContentDetector.DEFAULT_COMPONENT_WEIGHTS,
@@ -49,8 +50,9 @@ def __init__(
         Arguments:
             adaptive_threshold: Threshold (float) that score ratio must exceed to trigger a
                 new scene (see frame metric adaptive_ratio in stats file).
-            min_scene_len: Once a cut is detected, this many frames must pass before a new one can
-                be added to the scene list. Can be an int or FrameTimecode type.
+            min_scene_len: Once a cut is detected, this much time must pass before a new one can
+                be added to the scene list. Can be an int (frames), float (seconds), or str
+                (e.g. ``"0.6s"``).
             window_width: Size of window (number of frames) before and after each frame to
                 average together in order to detect deviations from the mean. Must be at least 1.
             min_content_val: Minimum threshold (float) that the content_val must exceed in order to