[api][cli] Rename temporal margin to margin

Much shorter and more concise.

Author: Breakthrough

scenedetect.cfg

@@ -232,7 +232,7 @@
 #frame-margin = 1
 
 # Amount of time to ignore at the beginning/end of a shot when selecting frames.
-#temporal-margin = 0.04s
+#margin = 0.04s
 
 # Resize by scale factor (0.5 = half, 1.0 = same, 2.0 = double).
 #scale = 1.0

scenedetect/_cli/__init__.py

@@ -1401,17 +1401,17 @@ def split_video_command(
     metavar="N",
     default=None,
     type=click.INT,
-    help="[DEPRECATED] Use --temporal-margin instead. Number of frames to ignore at beginning/end of scenes when saving images.%s"
+    help="[DEPRECATED] Use --margin instead. Number of frames to ignore at beginning/end of scenes when saving images.%s"
     % (USER_CONFIG.get_help_string("save-images", "frame-margin")),
 )
 @click.option(
     "-M",
-    "--temporal-margin",
+    "--margin",
     metavar="TIME",
     default=None,
     type=click.STRING,
     help="Amount of time to ignore at the beginning/end of each scene. Discards frame-margin if set. Can be specified as seconds (0.1), frames (3), or timecode (00:00:00.100).%s"
-    % (USER_CONFIG.get_help_string("save-images", "temporal-margin")),
+    % (USER_CONFIG.get_help_string("save-images", "margin")),
 )
 @click.option(
     "--scale",
@@ -1452,7 +1452,7 @@ def save_images_command(
     png: bool = False,
     compression: ty.Optional[int] = None,
     frame_margin: ty.Optional[int] = None,
-    temporal_margin: ty.Optional[str] = None,
+    margin: ty.Optional[str] = None,
     scale: ty.Optional[float] = None,
     height: ty.Optional[int] = None,
     width: ty.Optional[int] = None,
@@ -1498,13 +1498,11 @@ def save_images_command(
         raise click.BadParameter("\n".join(error_strs), param_hint="save-images")
     output = ctx.config.get_value("save-images", "output", output)
 
-    # Get temporal_margin value (from CLI arg or config), converting to FrameTimecode
-    temporal_margin_value = ctx.config.get_value("save-images", "temporal-margin", temporal_margin)
-    temporal_margin_tc = None
-    if temporal_margin_value is not None:
-        temporal_margin_tc = FrameTimecode(
-            timecode=temporal_margin_value, fps=ctx.video_stream.frame_rate
-        )
+    # Get margin value (from CLI arg or config), converting to FrameTimecode
+    margin_value = ctx.config.get_value("save-images", "margin", margin)
+    margin_tc = None
+    if margin_value is not None:
+        margin_tc = FrameTimecode(timecode=margin_value, fps=ctx.video_stream.frame_rate)
 
     save_images_args = {
         "encoder_param": compression if png else quality,
@@ -1517,7 +1515,7 @@ def save_images_command(
         "output": output,
         "scale": scale,
         "show_progress": not ctx.quiet_mode,
-        "temporal_margin": temporal_margin_tc,
+        "margin": margin_tc,
         "threading": ctx.config.get_value("save-images", "threading"),
         "width": width,
     }

scenedetect/_cli/commands.py

@@ -191,7 +191,7 @@ def save_images(
     width: int,
     interpolation: Interpolation,
     threading: bool,
-    temporal_margin: ty.Optional["FrameTimecode"] = None,
+    margin: ty.Optional["FrameTimecode"] = None,
 ):
     """Handles the `save-images` command."""
     del cuts  # save-images only uses scenes.
@@ -211,7 +211,7 @@ def save_images(
         width=width,
         interpolation=interpolation,
         threading=threading,
-        temporal_margin=temporal_margin,
+        margin=margin,
     )
     # Save the result for use by `save-html` if required.
     context.save_images_result = (images, output)

scenedetect/_cli/config.py

@@ -419,7 +419,7 @@ class XmlFormat(Enum):
         "quality": RangeValue(_PLACEHOLDER, min_val=0, max_val=100),
         "scale": 1.0,
         "scale-method": Interpolation.LINEAR,
-        "temporal-margin": TimecodeValue("0.04s"),
+        "margin": TimecodeValue("0.04s"),
         "threading": True,
         "width": 0,
     },

scenedetect/output/image.py

@@ -77,7 +77,7 @@ def __init__(
         height: ty.Optional[int] = None,
         width: ty.Optional[int] = None,
         interpolation: Interpolation = Interpolation.CUBIC,
-        temporal_margin: ty.Optional[FrameTimecode] = None,
+        margin: ty.Optional[FrameTimecode] = None,
     ):
         """Multi-threaded implementation of save-images functionality. Uses background threads to
         handle image encoding and saving images to disk to improve parallelism.
@@ -89,7 +89,7 @@ def __init__(
             frame_margin: [DEPRECATED] Number of frames to pad each scene around the beginning
                 and end (e.g. moves the first/last image into the scene by N frames).
                 Can set to 0, but will result in some video files failing to extract
-                the very last frame. Use `temporal_margin` instead.
+                the very last frame. Use `margin` instead.
             image_extension: Type of image to save (must be one of 'jpg', 'png', or 'webp').
             encoder_param: Quality/compression efficiency, based on type of image:
                 'jpg' / 'webp':  Quality 0-100, higher is better quality.  100 is lossless for webp.
@@ -110,14 +110,14 @@ def __init__(
                 Specifying only width will rescale the image to that number of pixels wide
                 while preserving the aspect ratio.
             interpolation: Type of interpolation to use when resizing images.
-            temporal_margin: Amount of time to ignore at the beginning/end of a scene when
+            margin: Amount of time to ignore at the beginning/end of a scene when
                 selecting frames. Can be specified as frames (int), seconds (float), or timecode
                 string when creating the FrameTimecode. Uses presentation time (PTS) for selection.
                 When set, takes precedence over `frame_margin`.
         """
         self._num_images = num_images
         self._frame_margin = frame_margin
-        self._temporal_margin = temporal_margin
+        self._margin = margin
         self._image_extension = image_extension
         self._image_name_template = image_name_template
         self._scale = scale
@@ -301,12 +301,12 @@ def _generate_scene_timecodes(
     ) -> ty.Iterable[FrameTimecode]:
         """Generate timecodes for images to extract from a single scene.
 
-        Uses temporal_margin to determine the effective time range, then distributes
+        Uses margin to determine the effective time range, then distributes
         images evenly across that range using time-based arithmetic.
         """
-        # Use temporal_margin if set, otherwise fall back to frame_margin converted to time
-        if self._temporal_margin is not None:
-            margin = self._temporal_margin
+        # Use margin if set, otherwise fall back to frame_margin converted to time
+        if self._margin is not None:
+            margin = self._margin
         elif self._frame_margin > 0:
             margin = FrameTimecode(self._frame_margin, fps=start.framerate)
         else:
@@ -371,7 +371,7 @@ def save_images(
     width: ty.Optional[int] = None,
     interpolation: Interpolation = Interpolation.CUBIC,
     threading: bool = True,
-    temporal_margin: ty.Optional[FrameTimecode] = None,
+    margin: ty.Optional[FrameTimecode] = None,
 ) -> ty.Dict[int, ty.List[str]]:
     """Save a set number of images from each scene, given a list of scenes
     and the associated video/frame source.
@@ -385,7 +385,7 @@ def save_images(
         frame_margin: Number of frames to pad each scene around the beginning
             and end (e.g. moves the first/last image into the scene by N frames).
             Can set to 0, but will result in some video files failing to extract
-            the very last frame. Discarded if `temporal_margin` is set.
+            the very last frame. Discarded if `margin` is set.
         image_extension: Type of image to save (must be one of 'jpg', 'png', or 'webp').
         encoder_param: Quality/compression efficiency, based on type of image:
             'jpg' / 'webp':  Quality 0-100, higher is better quality.  100 is lossless for webp.
@@ -410,7 +410,7 @@ def save_images(
             while preserving the aspect ratio.
         interpolation: Type of interpolation to use when resizing images.
         threading: Offload image encoding and disk IO to background threads to improve performance.
-        temporal_margin: Amount of time to pad each scene around the beginning and end. Takes
+        margin: Amount of time to pad each scene around the beginning and end. Takes
             precedence over `frame_margin` when set. Can be created from seconds (float), frames
             (int), or timecode string.
 
@@ -449,7 +449,7 @@ def save_images(
             height,
             width,
             interpolation,
-            temporal_margin,
+            margin,
         )
         return extractor.run(video, scene_list, output_dir, show_progress)
 
@@ -473,7 +473,7 @@ def save_images(
     extractor = _ImageExtractor(
         num_images=num_images,
         frame_margin=frame_margin,
-        temporal_margin=temporal_margin,
+        margin=margin,
     )
     timecode_list = [list(tc) for tc in extractor.generate_timecode_list(scene_list)]
 

tests/test_output.py

@@ -202,22 +202,20 @@ def test_deprecated_output_modules_emits_warning_on_import():
         from scenedetect.video_splitter import split_video_ffmpeg as _
 
 
-class TestImageExtractorTemporalMargin:
-    """Tests for _ImageExtractor temporal margin functionality using PTS-based selection."""
+class TestImageExtractorMargin:
+    """Tests for _ImageExtractor margin functionality using PTS-based selection."""
 
-    def test_temporal_margin_uses_seconds_not_frames(self):
-        """Test that temporal_margin operates on presentation time, not frame count.
+    def test_margin_uses_seconds_not_frames(self):
+        """Test that margin operates on presentation time, not frame count.
 
         With a 0.1s margin on a scene from 0s to 3s at 30fps:
         - First image should be at ~0.1s (frame 3)
         - Last image should be at ~2.9s (frame 87)
         """
         from scenedetect.output.image import _ImageExtractor
 
-        # 30 fps, 0.1s temporal margin
-        extractor = _ImageExtractor(
-            num_images=3, temporal_margin=FrameTimecode(timecode=0.1, fps=30.0)
-        )
+        # 30 fps, 0.1s margin
+        extractor = _ImageExtractor(num_images=3, margin=FrameTimecode(timecode=0.1, fps=30.0))
 
         # Scene from frame 0 to 90 (0s to 3s at 30fps)
         scene_list = [
@@ -233,18 +231,16 @@ def test_temporal_margin_uses_seconds_not_frames(self):
         # Last image: end.seconds - margin = 3.0 - 0.1 = 2.9s → frame 87
         assert timecodes[2].seconds == pytest.approx(2.9, abs=0.05)
 
-    def test_temporal_margin_different_framerates(self):
-        """Test temporal margin works consistently across different framerates.
+    def test_margin_different_framerates(self):
+        """Test margin works consistently across different framerates.
 
-        The same temporal margin (0.1s) should result in different frame offsets
+        The same margin (0.1s) should result in different frame offsets
         but the same time offset regardless of framerate.
         """
         from scenedetect.output.image import _ImageExtractor
 
         for fps in [24.0, 25.0, 30.0, 60.0]:
-            extractor = _ImageExtractor(
-                num_images=3, temporal_margin=FrameTimecode(timecode=0.1, fps=fps)
-            )
+            extractor = _ImageExtractor(num_images=3, margin=FrameTimecode(timecode=0.1, fps=fps))
             # 3 second scene
             scene_list = [
                 (FrameTimecode(0, fps=fps), FrameTimecode(int(3 * fps), fps=fps)),
@@ -256,14 +252,12 @@ def test_temporal_margin_different_framerates(self):
             assert timecodes[0].seconds == pytest.approx(0.1, abs=0.05), f"Failed at {fps}fps"
             assert timecodes[2].seconds == pytest.approx(2.9, abs=0.05), f"Failed at {fps}fps"
 
-    def test_temporal_margin_clamped_to_scene_bounds(self):
-        """Test that temporal margin is clamped when scene is shorter than 2x margin."""
+    def test_margin_clamped_to_scene_bounds(self):
+        """Test that margin is clamped when scene is shorter than 2x margin."""
         from scenedetect.output.image import _ImageExtractor
 
         # 0.5s margin on a 0.5s scene - should clamp to scene bounds
-        extractor = _ImageExtractor(
-            num_images=3, temporal_margin=FrameTimecode(timecode=0.5, fps=30.0)
-        )
+        extractor = _ImageExtractor(num_images=3, margin=FrameTimecode(timecode=0.5, fps=30.0))
 
         # Scene from frame 0 to 15 (0s to 0.5s at 30fps)
         scene_list = [
@@ -276,13 +270,11 @@ def test_temporal_margin_clamped_to_scene_bounds(self):
         for tc in timecodes:
             assert 0.0 <= tc.seconds <= 0.5
 
-    def test_temporal_margin_zero(self):
-        """Test that zero temporal margin selects frames at scene boundaries."""
+    def test_margin_zero(self):
+        """Test that zero margin selects frames at scene boundaries."""
         from scenedetect.output.image import _ImageExtractor
 
-        extractor = _ImageExtractor(
-            num_images=3, temporal_margin=FrameTimecode(timecode=0.0, fps=30.0)
-        )
+        extractor = _ImageExtractor(num_images=3, margin=FrameTimecode(timecode=0.0, fps=30.0))
 
         scene_list = [
             (FrameTimecode(30, fps=30.0), FrameTimecode(90, fps=30.0)),
@@ -295,11 +287,11 @@ def test_temporal_margin_zero(self):
         # Last image near scene end (3s)
         assert timecodes[2].seconds == pytest.approx(2.97, abs=0.1)
 
-    def test_temporal_margin_with_pts_timecodes(self):
-        """Test temporal margin works correctly with PTS-based FrameTimecodes.
+    def test_margin_with_pts_timecodes(self):
+        """Test margin works correctly with PTS-based FrameTimecodes.
 
         PTS (Presentation Time Stamp) based timecodes use a time_base rather than
-        a fixed framerate. This test verifies that temporal margin calculations
+        a fixed framerate. This test verifies that margin calculations
         work correctly when scenes are defined using PTS.
         """
         from fractions import Fraction
@@ -314,10 +306,10 @@ def test_temporal_margin_with_pts_timecodes(self):
         start = FrameTimecode(timecode=Timecode(pts=0, time_base=time_base), fps=30.0)
         end = FrameTimecode(timecode=Timecode(pts=3000, time_base=time_base), fps=30.0)
 
-        # 100ms (0.1s) temporal margin, also as PTS-based
+        # 100ms (0.1s) margin, also as PTS-based
         margin = FrameTimecode(timecode=Timecode(pts=100, time_base=time_base), fps=30.0)
 
-        extractor = _ImageExtractor(num_images=3, temporal_margin=margin)
+        extractor = _ImageExtractor(num_images=3, margin=margin)
 
         scene_list = [(start, end)]
         timecode_list = extractor.generate_timecode_list(scene_list)
@@ -330,7 +322,7 @@ def test_temporal_margin_with_pts_timecodes(self):
         # Last image: 3s - 0.1s margin = 2.9s
         assert timecodes[2].seconds == pytest.approx(2.9, abs=0.05)
 
-    def test_temporal_margin_pts_preserves_time_base(self):
+    def test_margin_pts_preserves_time_base(self):
         """Test that output timecodes preserve the time_base from input PTS timecodes."""
         from fractions import Fraction
 
@@ -346,7 +338,7 @@ def test_temporal_margin_pts_preserves_time_base(self):
         # 0.1s margin = 9000 pts at 1/90000 time_base
         margin = FrameTimecode(timecode=Timecode(pts=9000, time_base=time_base), fps=30.0)
 
-        extractor = _ImageExtractor(num_images=2, temporal_margin=margin)
+        extractor = _ImageExtractor(num_images=2, margin=margin)
 
         scene_list = [(start, end)]
         timecode_list = extractor.generate_timecode_list(scene_list)
@@ -357,7 +349,7 @@ def test_temporal_margin_pts_preserves_time_base(self):
         assert timecodes[1].seconds == pytest.approx(1.9, abs=0.01)
 
     def test_frame_margin_backwards_compatibility(self):
-        """Test that frame_margin still works when temporal_margin is not set.
+        """Test that frame_margin still works when margin is not set.
 
         This ensures backwards compatibility with existing code using frame_margin.
         """
@@ -380,16 +372,16 @@ def test_frame_margin_backwards_compatibility(self):
         # Last image: 3s - 3 frames = 2.9s
         assert timecodes[2].seconds == pytest.approx(2.9, abs=0.05)
 
-    def test_temporal_margin_overrides_frame_margin(self):
-        """Test that temporal_margin takes precedence over frame_margin when both are set."""
+    def test_margin_overrides_frame_margin(self):
+        """Test that margin takes precedence over frame_margin when both are set."""
         from scenedetect.output.image import _ImageExtractor
 
-        # Set frame_margin to 30 frames (1s at 30fps), but temporal_margin to 0.1s
-        # temporal_margin should win
+        # Set frame_margin to 30 frames (1s at 30fps), but margin to 0.1s
+        # margin should win
         extractor = _ImageExtractor(
             num_images=3,
             frame_margin=30,  # Would be 1s at 30fps
-            temporal_margin=FrameTimecode(timecode=0.1, fps=30.0),  # 0.1s
+            margin=FrameTimecode(timecode=0.1, fps=30.0),  # 0.1s
         )
 
         scene_list = [
@@ -398,6 +390,6 @@ def test_temporal_margin_overrides_frame_margin(self):
         timecode_list = extractor.generate_timecode_list(scene_list)
         timecodes = list(timecode_list[0])
 
-        # Should use temporal_margin (0.1s), not frame_margin (1s)
+        # Should use margin (0.1s), not frame_margin (1s)
         assert timecodes[0].seconds == pytest.approx(0.1, abs=0.05)
         assert timecodes[2].seconds == pytest.approx(2.9, abs=0.05)