scenedetect 0.7.1.dev0__tar.gz → 0.7.2__tar.gz

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scenedetect
-Version: 0.7.1.dev0
+Version: 0.7.2
 Summary: Video scene cut/shot detection program and Python library (bundles the opencv-python OpenCV variant and the scenedetect CLI).
 Author-email: Brandon Castellano <brandon248@gmail.com>
 License-Expression: BSD-3-Clause
@@ -66,7 +66,7 @@ Github Repo: https://github.com/Breakthrough/PySceneDetect/
 
 Install: ``pip install --upgrade scenedetect`` (or ``scenedetect-headless`` for servers)
 
-Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``), `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``), and `scenedetect-core <https://pypi.org/project/scenedetect-core/>`_ (library only, minimal dependencies, bring your own OpenCV variant). All provide the same ``scenedetect`` module -- install only one.
+Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``) and `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``). Both provide the same ``scenedetect`` module -- install only one.
 
 ----------------------------------------------------------
 

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/README.md

@@ -13,7 +13,7 @@
 
 ----------------------------------------------------------
 
-### Latest Release: v0.7 (May 3, 2026)
+### Latest Release: v0.7.2 (October 11, 2026)
 
 **Website**:  [scenedetect.com](https://www.scenedetect.com)
 
@@ -29,7 +29,7 @@
 
     pip install scenedetect --upgrade
 
-Requires ffmpeg/mkvmerge for video splitting support. Windows builds (MSI installer/portable ZIP) can be found on [the download page](https://scenedetect.com/download/).
+Requires ffmpeg/mkvmerge for video splitting support. Windows builds (MSI installer/portable ZIP) can be found on [the download page](https://scenedetect.com/download/). A Docker image with all dependencies included is available as [`ghcr.io/breakthrough/pyscenedetect`](https://github.com/Breakthrough/PySceneDetect/pkgs/container/pyscenedetect).
 
 ----------------------------------------------------------
 
@@ -49,13 +49,20 @@ Skip the first 10 seconds of the input video:
 
 More examples can be found throughout [the documentation](https://www.scenedetect.com/docs/latest/cli.html).
 
+**Quick Start (Docker)**:
+
+The same commands work without installing anything using [the official Docker image](https://github.com/Breakthrough/PySceneDetect/pkgs/container/pyscenedetect), which includes all dependencies (`ffmpeg`/`mkvmerge` included). Mount the folder containing your videos and use it for input/output paths:
+
+    docker run --rm -v "$(pwd):/files" ghcr.io/breakthrough/pyscenedetect -i /files/video.mp4 split-video -o /files
+
 **Quick Start (Python API)**:
 
 To get started, there is a high level function in the library that performs content-aware scene detection on a video (try it from a Python prompt):
 
 ```python
 from scenedetect import detect, ContentDetector
-scene_list = detect('my_video.mp4', ContentDetector())
+
+scene_list = detect("my_video.mp4", ContentDetector())
 ```
 
 `scene_list` will now be a list containing the start/end times of all scenes found in the video.  There also exists a two-pass version `AdaptiveDetector` which handles fast camera movement better, and `ThresholdDetector` for handling fade out/fade in events.
@@ -64,20 +71,28 @@ Try calling `print(scene_list)`, or iterating over each scene:
 
 ```python
 from scenedetect import detect, ContentDetector
-scene_list = detect('my_video.mp4', ContentDetector())
+
+scene_list = detect("my_video.mp4", ContentDetector())
 for i, scene in enumerate(scene_list):
-    print('    Scene %2d: Start %s / Frame %d, End %s / Frame %d' % (
-        i+1,
-        scene[0].get_timecode(), scene[0].frame_num,
-        scene[1].get_timecode(), scene[1].frame_num,))
+    print(
+        "    Scene %2d: Start %s / Frame %d, End %s / Frame %d"
+        % (
+            i + 1,
+            scene[0].get_timecode(),
+            scene[0].frame_num,
+            scene[1].get_timecode(),
+            scene[1].frame_num,
+        )
+    )
 ```
 
 We can also split the video into each scene if `ffmpeg` is installed (`mkvmerge` is also supported):
 
 ```python
 from scenedetect import detect, ContentDetector, split_video_ffmpeg
-scene_list = detect('my_video.mp4', ContentDetector())
-split_video_ffmpeg('my_video.mp4', scene_list)
+
+scene_list = detect("my_video.mp4", ContentDetector())
+split_video_ffmpeg("my_video.mp4", scene_list)
 ```
 
 For more advanced usage, the API is highly configurable, and can easily integrate with any pipeline. This includes using different detection algorithms, splitting the input video, and much more. The following example shows how to implement a function similar to the above, but using [the `scenedetect` API](https://www.scenedetect.com/docs/latest/api.html):
@@ -87,12 +102,12 @@ from scenedetect import open_video, SceneManager, split_video_ffmpeg
 from scenedetect.detectors import ContentDetector
 from scenedetect.video_splitter import split_video_ffmpeg
 
+
 def split_video_into_scenes(video_path, threshold=27.0):
     # Open our video, create a scene manager, and add a detector.
     video = open_video(video_path)
     scene_manager = SceneManager()
-    scene_manager.add_detector(
-        ContentDetector(threshold=threshold))
+    scene_manager.add_detector(ContentDetector(threshold=threshold))
     scene_manager.detect_scenes(video, show_progress=True)
     scene_list = scene_manager.get_scene_list()
     split_video_ffmpeg(video_path, scene_list, show_progress=True)
@@ -102,13 +117,13 @@ See [the documentation](https://www.scenedetect.com/docs/latest/api.html) for mo
 
 **Benchmark**:
 
-We evaluate the performance of different detectors in terms of accuracy and processing speed. See the [benchmark report](benchmark/README.md) for details.
+We evaluate the performance of different detectors in terms of accuracy and processing speed. See [www.scenedetect.com/benchmarks](https://www.scenedetect.com/benchmarks/) for results, or the [benchmark report](benchmark/README.md) for details on the datasets and methodology.
 
 ## Reference
 
  - [Documentation](https://www.scenedetect.com/docs/) (covers application and Python API)
  - [CLI Example](https://www.scenedetect.com/cli/)
- - [Config File](https://www.scenedetect.com/docs/0.6.4/cli/config_file.html)
+ - [Config File](https://www.scenedetect.com/docs/latest/cli/config_file.html)
 
 ## Help & Contributing
 

scenedetect-0.7.2/docs/LATEST_VERSION

@@ -0,0 +1 @@
+0.7.2

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/docs/api.rst

@@ -23,9 +23,9 @@ The `scenedetect` API is easy to integrate with most application workflows, whil
 
         * :func:`split_video_ffmpeg <scenedetect.output.split_video_ffmpeg>` and :func:`split_video_mkvmerge <scenedetect.output.split_video_mkvmerge>` split a video based on the detected scenes
 
-        * :func:`save_images <scenedetect.scene_manager.save_images>` can save an arbitrary number of images from each scene
+        * :func:`save_images <scenedetect.output.save_images>` can save an arbitrary number of images from each scene
 
-        * :func:`write_scene_list <scenedetect.scene_manager.write_scene_list>` can be used to save scene/cut info as CSV, :func:`write_scene_list_html <scenedetect.scene_manager.write_scene_list_html>` for HTML
+        * :func:`write_scene_list <scenedetect.output.write_scene_list>` can be used to save scene/cut info as CSV, :func:`write_scene_list_html <scenedetect.output.write_scene_list_html>` for HTML
 
     * :ref:`scenedetect.backends 🎥 <scenedetect-backends>`: PySceneDetect supports multiple libraries as an input backend:
 
@@ -58,7 +58,7 @@ Most types/functions are also available directly from the `scenedetect` package
 
     .. code:: python
 
-        scenedetect<0.8
+        scenedetect~=0.7
 
 
 .. _scenedetect-quickstart:

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/docs/cli/backends.rst

@@ -19,7 +19,7 @@ The `OpenCV <https://opencv.org/>`_ backend (usually `opencv-python <https://pyp
 
 It is mostly reliable and fast, although can occasionally run into issues processing videos with multiple audio tracks or small amounts of frame corruption. You can use a custom version of the ``cv2`` package, or install either the `opencv-python` or `opencv-python-headless` packages from `pip`.
 
-The OpenCV backend also supports image sequences as inputs (e.g. ``frame%02d.jpg`` if you want to load frame001.jpg, frame002.jpg, frame003.jpg...). Make sure to specify the framerate manually (``-f``/``--framerate``) to ensure accurate timing calculations.
+The OpenCV backend also supports image sequences as inputs (e.g. ``frame%02d.jpg`` if you want to load frame001.jpg, frame002.jpg, frame003.jpg...). Make sure to specify the framerate manually (``-f``/``--frame-rate``) to ensure accurate timing calculations.
 
 Variable framerate (VFR) video is supported. Scene detection uses PTS-derived timestamps from ``CAP_PROP_POS_MSEC`` for accurate timecodes. Seeking compensates for OpenCV's average-fps-based internal seek approximation, so output timecodes remain accurate across the full video.
 

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/docs/cli.rst

@@ -61,9 +61,9 @@ Options
 
   Stats file (.csv) to write frame metrics. Existing files will be overwritten. Used for tuning detection parameters and data analysis.
 
-.. option:: -f FPS, --framerate FPS
+.. option:: -f FPS, --framerate FPS, --frame-rate FPS
 
-  Override framerate with value as frames/sec.
+  Override frame rate with value as frames/sec.
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
@@ -308,13 +308,13 @@ Options
 
   Max distance between hash values (0.0 to 1.0) of adjacent frames. Lower values are more sensitive to changes.
 
-  Default: ``0.395``
+  Default: ``0.35``
 
 .. option:: -s SIZE, --size SIZE
 
   Size of square of low frequency data to include from the discrete cosine transform.
 
-  Default: ``16``
+  Default: ``8``
 
 .. option:: -l FRAC, --lowpass FRAC
 
@@ -359,13 +359,13 @@ Options
 
   Max difference (0.0 to 1.0) between histograms of adjacent frames. Lower values are more sensitive to changes.
 
-  Default: ``0.05``
+  Default: ``0.2``
 
 .. option:: -b NUM, --bins NUM
 
   The number of bins to use for the histogram calculation.
 
-  Default: ``256``
+  Default: ``128``
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
@@ -416,6 +416,12 @@ Options
 
   Default: ``True``
 
+.. option:: --min-out-length TIMECODE
+
+  Minimum time spent faded out before a cut is allowed. Ignores shorter fades even when the minimum scene length is met. Also applies to a final fade-out, including the last processed frame. Zero allows fades of any duration. TIMECODE can be specified in frames (4), seconds with an `s` suffix (0.4s), or timecode (00:00:00.400).
+
+  Default: ``0.1s``. The Python API default remains ``0``.
+
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
   Minimum length of any scene. Overrides global option :option:`-m/--min-scene-len <scenedetect -m>`. TIMECODE can be specified in frames (-m 100), in seconds with `s` suffix (-m 3.5s), or timecode (-m 00:01:52.778).
@@ -549,6 +555,10 @@ Options
 
   Output directory to save EDL file to. Overrides global option :option:`-o/--output <scenedetect -o>`.
 
+.. option:: -s TIMECODE, --start-timecode TIMECODE
+
+  Start timecode added to every event so the EDL aligns with the source media's on-screen timecode. Accepts SMPTE HH:MM:SS:FF or 8 digits (HHMMSSFF, e.g. 01000000).
+
 
 .. _command-save-fcp:
 
@@ -707,6 +717,34 @@ Options
   Width (pixels) of images.
 
 
+.. _command-save-keyframes:
+
+.. program:: scenedetect save-keyframes
+
+
+``save-keyframes``
+========================================================================
+
+Save detected cuts using keyframe format v1.
+
+Frame numbers are currently approximate for variable framerate (VFR) video.
+
+
+Options
+------------------------------------------------------------------------
+
+
+.. option:: -f NAME, --filename NAME
+
+  Filename format to use.
+
+  Default: ``$VIDEO_NAME-keyframes.txt``
+
+.. option:: -o DIR, --output DIR
+
+  Output directory to save keyframes to. Overrides global option :option:`-o/--output <scenedetect -o>`.
+
+
 .. _command-save-otio:
 
 .. program:: scenedetect save-otio
@@ -859,7 +897,7 @@ Options
 
 .. option:: --expand
 
-  Extend the first/last output clips to cover the full input video, even if the :ref:`time <command-time>` command's ``--start``/``--end`` limited the analysis window. Useful for keeping content outside the analyzed region attached to the adjacent split.
+  Extend the first/last output clips to cover the full input video, even if `time -s/-e` limited the analysis window. Useful for keeping content outside the analyzed region attached to the adjacent split.
 
 
 .. _command-time:

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/docs/index.rst

@@ -8,7 +8,7 @@ PySceneDetect Documentation
 
 Welcome to the PySceneDetect docs. The docs are split into two separate parts: one for the command-line interface (the `scenedetect` command) and another for the Python API (the `scenedetect` module).
 
-You can install the latest release of PySceneDetect by running `pip install scenedetect` (or `pip install scenedetect-headless` on servers without GUI libraries), or by downloading the Windows build from `scenedetect.com/download <http://www.scenedetect.com/download/>`_. Library-only installs that need a specific OpenCV variant (e.g. `opencv-contrib-python`) can use `pip install scenedetect-core`, which has no CLI dependencies and lets you supply any OpenCV package. PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
+You can install the latest release of PySceneDetect by running `pip install scenedetect` (or `pip install scenedetect-headless` on servers without GUI libraries), or by downloading the Windows build from `scenedetect.com/download <http://www.scenedetect.com/download/>`_. PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
 
 .. note::
 

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/packaging/package-info.rst

@@ -25,7 +25,7 @@ Github Repo: https://github.com/Breakthrough/PySceneDetect/
 
 Install: ``pip install --upgrade scenedetect`` (or ``scenedetect-headless`` for servers)
 
-Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``), `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``), and `scenedetect-core <https://pypi.org/project/scenedetect-core/>`_ (library only, minimal dependencies, bring your own OpenCV variant). All provide the same ``scenedetect`` module -- install only one.
+Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``) and `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``). Both provide the same ``scenedetect`` module -- install only one.
 
 ----------------------------------------------------------
 

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/__init__.py

@@ -15,6 +15,7 @@ can be used to open a video for a
 :class:`SceneManager <scenedetect.scene_manager.SceneManager>`.
 """
 
+import warnings
 from logging import getLogger
 
 # OpenCV is a required package, but we don't have it as an explicit dependency since we
@@ -30,54 +31,56 @@ except ModuleNotFoundError as ex:
 
 # Commonly used classes/functions exported under the `scenedetect` namespace for brevity.
 # Note that order of importants is important!
-from scenedetect.platform import init_logger  # noqa: I001
+from scenedetect.platform import init_logger as init_logger  # noqa: I001
 from scenedetect.common import (
-    FrameTimecode,
-    FrameRate,
-    SceneList,
-    CutList,
-    CropRegion,
-    TimecodePair,
-    TimecodeLike,
-    Interpolation,
+    FrameTimecode as FrameTimecode,
+    FrameRate as FrameRate,
+    SceneList as SceneList,
+    CutList as CutList,
+    CropRegion as CropRegion,
+    TimecodePair as TimecodePair,
+    TimecodeLike as TimecodeLike,
+    Interpolation as Interpolation,
 )
-from scenedetect.platform import StrPath
-from scenedetect.video_stream import VideoStream, VideoOpenFailure
+from scenedetect.platform import StrPath as StrPath
+from scenedetect.video_stream import VideoStream as VideoStream
+from scenedetect.video_stream import VideoOpenFailure as VideoOpenFailure
 from scenedetect.output import (
-    save_images,
-    split_video_ffmpeg,
-    split_video_mkvmerge,
-    is_ffmpeg_available,
-    is_mkvmerge_available,
-    write_scene_list,
-    write_scene_list_html,
-    PathFormatter,
-    VideoMetadata,
-    SceneMetadata,
+    save_images as save_images,
+    split_video_ffmpeg as split_video_ffmpeg,
+    split_video_mkvmerge as split_video_mkvmerge,
+    is_ffmpeg_available as is_ffmpeg_available,
+    is_mkvmerge_available as is_mkvmerge_available,
+    write_scene_list as write_scene_list,
+    write_scene_list_html as write_scene_list_html,
+    PathFormatter as PathFormatter,
+    VideoMetadata as VideoMetadata,
+    SceneMetadata as SceneMetadata,
 )
-from scenedetect.detector import SceneDetector
+from scenedetect.detector import SceneDetector as SceneDetector
 from scenedetect.detectors import (
-    ContentDetector,
-    AdaptiveDetector,
-    ThresholdDetector,
-    HistogramDetector,
-    HashDetector,
+    ContentDetector as ContentDetector,
+    AdaptiveDetector as AdaptiveDetector,
+    ThresholdDetector as ThresholdDetector,
+    HistogramDetector as HistogramDetector,
+    HashDetector as HashDetector,
 )
 from scenedetect.backends import (
-    AVAILABLE_BACKENDS,
-    VideoStreamCv2,
-    VideoStreamAv,
-    VideoStreamMoviePy,
-    VideoCaptureAdapter,
-    VideoStreamConcat,
-    SourceSpan,
+    AVAILABLE_BACKENDS as AVAILABLE_BACKENDS,
+    VideoStreamCv2 as VideoStreamCv2,
+    VideoStreamAv as VideoStreamAv,
+    VideoStreamMoviePy as VideoStreamMoviePy,
+    VideoCaptureAdapter as VideoCaptureAdapter,
+    VideoStreamConcat as VideoStreamConcat,
+    SourceSpan as SourceSpan,
 )
-from scenedetect.stats_manager import StatsManager, StatsFileCorrupt
+from scenedetect.stats_manager import StatsManager as StatsManager
+from scenedetect.stats_manager import StatsFileCorrupt as StatsFileCorrupt
 from scenedetect.scene_manager import SceneManager
 
 # Used for module identification and when printing version & about info
 # (e.g. calling `scenedetect version` or `scenedetect about`).
-__version__ = "0.7.1-dev0"
+__version__ = "0.7.2"
 
 init_logger()
 logger = getLogger("pyscenedetect")
@@ -113,8 +116,13 @@ def open_video(
         :class:`VideoOpenFailure`: Constructing the VideoStream fails. If multiple backends have
             been attempted, the error from the first backend will be returned.
     """
-    # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-    # used, once internal callers and downstream users have had a release to migrate.
+    if framerate is not None:
+        warnings.warn(
+            "`framerate` is deprecated and scheduled for removal in v0.9; "
+            "use `frame_rate` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
     if frame_rate is None:
         frame_rate = framerate
     # A list of paths is opened as a single concatenated stream. VideoStreamConcat handles

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/_cli/__init__.py

@@ -22,7 +22,6 @@ import inspect
 import logging
 import os
 import os.path
-import typing as ty
 from copy import copy
 
 import click
@@ -231,6 +230,7 @@ Global options (e.g. -i/--input, -c/--config) must be specified before any comma
 )
 @click.option(
     "--frame-rate",
+    "--framerate",
     "-f",
     "frame_rate",
     metavar="FPS",
@@ -238,15 +238,6 @@ Global options (e.g. -i/--input, -c/--config) must be specified before any comma
     default=None,
     help="Override frame rate with value as frames/sec.",
 )
-@click.option(
-    "--framerate",
-    "framerate_legacy",
-    metavar="FPS",
-    type=click.FLOAT,
-    default=None,
-    hidden=True,
-    help="[DEPRECATED] Use -f/--frame-rate instead.",
-)
 @click.option(
     "--min-scene-len",
     "-m",
@@ -347,7 +338,6 @@ def scenedetect(
     stats: str | None,
     config: str | None,
     frame_rate: float | None,
-    framerate_legacy: float | None,
     min_scene_len: str | None,
     drop_short_scenes: bool | None,
     merge_last_scene: bool | None,
@@ -362,13 +352,6 @@ def scenedetect(
     ctx = ctx.obj
     assert isinstance(ctx, CliContext)
 
-    # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `--framerate`
-    # is used, once downstream users have had a release to migrate to `--frame-rate`.
-    if frame_rate is None:
-        frame_rate = framerate_legacy
-    elif framerate_legacy is not None:
-        logger.warning("Both --frame-rate and --framerate were specified; using --frame-rate.")
-
     ctx.handle_options(
         input_path=input,
         output=output,
@@ -516,6 +499,19 @@ def time_command(
     ctx.duration = ctx.parse_timecode(duration)
     if ctx.start_time and ctx.end_time and (ctx.start_time + 1) > ctx.end_time:
         raise click.BadParameter("-e/--end time must be greater than -s/--start")
+    # Reject start times past EOF before any backend seeks. OpenCV/PyAV previously
+    # continued and produced inconsistent errors; MoviePy raised SeekError (#380).
+    video_duration = ctx.video_stream.duration if ctx.video_stream is not None else None
+    if (
+        ctx.start_time is not None
+        and video_duration is not None
+        and video_duration > 0
+        and ctx.start_time >= video_duration
+    ):
+        raise click.BadParameter(
+            "start time is beyond the end of the video",
+            param_hint="-s/--start",
+        )
 
 
 DETECT_CONTENT_HELP = """Find fast cuts using differences in HSL (filtered).
@@ -780,6 +776,15 @@ Examples:
         USER_CONFIG.get_help_string("detect-threshold", "add-last-scene")
     ),
 )
+@click.option(
+    "--min-out-length",
+    metavar="TIMECODE",
+    type=click.STRING,
+    default=None,
+    help="Minimum time spent faded out before a cut is allowed. Ignores shorter fades even when the minimum scene length is met. Also applies to a final fade-out, including the last processed frame. Zero allows fades of any duration. TIMECODE can be specified in frames (4), seconds with an `s` suffix (0.4s), or timecode (00:00:00.400).{}".format(
+        USER_CONFIG.get_help_string("detect-threshold", "min-out-length")
+    ),
+)
 @click.option(
     "--min-scene-len",
     "-m",
@@ -800,6 +805,7 @@ def detect_threshold_command(
     fade_bias: float | None,
     add_last_scene: bool,
     min_scene_len: str | None,
+    min_out_length: str | None,
 ):
     ctx = ctx.obj
     assert isinstance(ctx, CliContext)
@@ -808,6 +814,7 @@ def detect_threshold_command(
         fade_bias=fade_bias,
         add_last_scene=add_last_scene,
         min_scene_len=min_scene_len,
+        min_out_length=min_out_length,
     )
     ctx.add_detector(ThresholdDetector, detector_args)
 
@@ -1714,6 +1721,48 @@ def save_qp_command(
     ctx.add_command(cli_commands.save_qp, save_qp_args)
 
 
+SAVE_KEYFRAMES_HELP = """Save detected cuts using keyframe format v1.
+
+Frame numbers are currently approximate for variable framerate (VFR) video.
+"""
+
+
+@click.command("save-keyframes", cls=Command, help=SAVE_KEYFRAMES_HELP)
+@click.option(
+    "--filename",
+    "-f",
+    metavar="NAME",
+    default=None,
+    type=click.STRING,
+    help="Filename format to use.{}".format(
+        USER_CONFIG.get_help_string("save-keyframes", "filename")
+    ),
+)
+@click.option(
+    "--output",
+    "-o",
+    metavar="DIR",
+    type=click.Path(exists=False, dir_okay=True, writable=True, resolve_path=False),
+    help="Output directory to save keyframes to. Overrides global option -o/--output.{}".format(
+        USER_CONFIG.get_help_string("save-keyframes", "output", show_default=False)
+    ),
+)
+@click.pass_context
+def save_keyframes_command(
+    ctx: click.Context,
+    filename: str | None,
+    output: str | None,
+):
+    ctx = ctx.obj
+    assert isinstance(ctx, CliContext)
+
+    save_keyframes_args = {
+        "filename": ctx.config.get_value("save-keyframes", "filename", filename),
+        "output": ctx.config.get_value("save-keyframes", "output", output),
+    }
+    ctx.add_command(cli_commands.save_keyframes, save_keyframes_args)
+
+
 SAVE_FCP_HELP = """Save cuts in Final Cut Pro XML format (FCP7 xmeml or FCPX)."""
 
 
@@ -1858,6 +1907,7 @@ scenedetect.add_command(save_edl_command)
 scenedetect.add_command(save_html_command)
 scenedetect.add_command(save_images_command)
 scenedetect.add_command(save_qp_command)
+scenedetect.add_command(save_keyframes_command)
 scenedetect.add_command(save_fcp_command)
 scenedetect.add_command(save_otio_command)
 scenedetect.add_command(split_video_command)

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/_cli/commands.py

@@ -102,6 +102,29 @@ def save_qp(
     logger.info(f"QP file written to: {qp_path}")
 
 
+def save_keyframes(
+    context: CliContext, scenes: SceneList, cuts: CutList, output: str, filename: str
+):
+    """Handler for the `save-keyframes` command."""
+    del scenes  # We only use cuts for this handler.
+    assert context.video_stream is not None
+    keyframes_path = get_and_create_path(
+        Template(filename).safe_substitute(VIDEO_NAME=context.video_stream.name),
+        output,
+    )
+    with open(keyframes_path, "w") as keyframes_file:
+        keyframes_file.write("# keyframe format v1\n")
+        # The keyframe format v1 specification includes an FPS field, but Aegisub does not
+        # use it and documents `0` as the conventional value:
+        # https://aegisub.org/docs/latest/video/#keyframe-file-specification
+        keyframes_file.write("fps 0\n")
+        keyframes_file.write("0\n")
+        # TODO(https://scenedetect.com/issues/569): Frame numbers are approximate for VFR
+        # input until exact presentation-frame ordinals are tracked.
+        keyframes_file.writelines(f"{cut.frame_num}\n" for cut in cuts)
+    logger.info(f"Keyframes written to: {keyframes_path}")
+
+
 def list_scenes(
     context: CliContext,
     scenes: SceneList,

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/_cli/config.py

@@ -379,17 +379,18 @@ CONFIG_MAP: ConfigDict = {
     "detect-hash": {
         "min-scene-len": TimecodeValue(0),
         "lowpass": RangeValue(2, min_val=1, max_val=256),
-        "size": RangeValue(16, min_val=1, max_val=256),
-        "threshold": RangeValue(0.395, min_val=0.0, max_val=1.0),
+        "size": RangeValue(8, min_val=1, max_val=256),
+        "threshold": RangeValue(0.35, min_val=0.0, max_val=1.0),
     },
     "detect-hist": {
         "min-scene-len": TimecodeValue(0),
-        "threshold": RangeValue(0.05, min_val=0.0, max_val=1.0),
-        "bins": RangeValue(256, min_val=1, max_val=256),
+        "threshold": RangeValue(0.20, min_val=0.0, max_val=1.0),
+        "bins": RangeValue(128, min_val=1, max_val=256),
     },
     "detect-threshold": {
         "add-last-scene": True,
         "fade-bias": RangeValue(0, min_val=-100.0, max_val=100.0),
+        "min-out-length": TimecodeValue("0.1s"),
         "min-scene-len": TimecodeValue(0),
         "threshold": RangeValue(12.0, min_val=0.0, max_val=255.0),
     },
@@ -460,6 +461,10 @@ CONFIG_MAP: ConfigDict = {
         "filename": "$VIDEO_NAME.qp",
         "output": None,
     },
+    "save-keyframes": {
+        "filename": "$VIDEO_NAME-keyframes.txt",
+        "output": None,
+    },
     "save-fcp": {
         "format": FcpFormat.FCPX,
         "filename": "$VIDEO_NAME.xml",

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/_cli/context.py

@@ -405,6 +405,7 @@ class CliContext:
         fade_bias: float | None = None,
         add_last_scene: bool | None = None,
         min_scene_len: str | None = None,
+        min_out_length: str | None = None,
     ) -> dict[str, ty.Any]:
         """Handle detect-threshold command options and return args to construct one with."""
 
@@ -415,6 +416,9 @@ class CliContext:
             or self.config.get_value("detect-threshold", "add-last-scene"),
             "fade_bias": self.config.get_value("detect-threshold", "fade-bias", fade_bias),
             "min_scene_len": min_scene_len_frames,
+            "min_out_length": self.parse_timecode(
+                self.config.get_value("detect-threshold", "min-out-length", min_out_length)
+            ),
             "threshold": self.config.get_value("detect-threshold", "threshold", threshold),
         }
 

{scenedetect-0.7.1.dev0 → scenedetect-0.7.2}/scenedetect/_cli/controller.py

@@ -131,7 +131,6 @@ def _detect(context: CliContext) -> tuple[SceneList, CutList] | None:
     )
 
     # Handle case where video failure is most likely due to multiple audio tracks (#179).
-    # TODO(https://scenedetect.com/issues/380): Ensure this does not erroneusly fire.
     if num_frames <= 0 and isinstance(context.video_stream, VideoStreamCv2):
         logger.critical(
             "Failed to read any frames from video file. This could be caused by the video"