PySceneDetect

BreakthroughBSD-3-Clause活跃维护

基于 Python 和 OpenCV 的视频场景切换检测工具与库，能自动识别视频中的镜头切换和转场，方便做视频分段、剪辑和内容分析。

:movie_camera: Python and OpenCV-based scene cut/transition detection program & library.

v0.7.3发布于 2026-11-08 22:44 UTC5,414star +11 / 7 天564fork同步于 2026-11-10 05:35 UTC

场景检测视频处理镜头切换 OpenCV 视频分析

对比 GitHub 官网 analysis image-processing opencv python python-opencv

怎么上手

README 里没有找到可直接复制的安装命令

原文

README 里没有找到可直接复制的安装命令，请到 README 或官方文档查看安装方式。

硬件要求按 README 关键词推断

有 Docker 镜像

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

这个项目的说明还在生成中，先参考下面「最近发版」和 README。

最近发版

5 个版本v0.7.3

全部 release

v0.7.3PySceneDetect v0.7.3最新正式版2026-11-08 · 2026-11-08 22:44 UTC
PySceneDetect 0.7.3 adds scene-length based image export to save-images, a close() method and context manager support for VideoStream, and fixes several timing bugs: PyAV frame timing for videos without presentation timestamps, save-edl timecode drift at NTSC frame rates, OTIO source durations, and the last scene of variable framerate videos. Windows distributions ship updated dependencies.

CLI Changes
- [feature] Add -i/--interval to save-images to save images based on the length of each scene: one image per DURATION, with --min-images/--max-images to limit the number of images per scene, e.g. save-images -i 2s --max-images 10 (interval/min-images/max-images in the config file, and interval/min_images/max_images in save_images()) #280
- [cli] --help now prints [default: ...] and [setting: ...] values as they are written in a config file (merge, fcpx, yes/no instead of Mode.MERGE, FcpFormat.FCPX, True/on), the [backend-pyav] threading-mode config value is now validated, and the scenedetect.cfg template matches the real config keys and defaults (verbosity, downscale, default-detector, fade-bias, start-timecode, OTIO name, and removed stale filter-mode/luma-only entries) #589
- [bugfix] $VIDEO_NAME is now derived from the path component of URL inputs, ignoring the query string and fragment (e.g. https://host/clip.mp4?token=1.2 -> clip). URLs with no path use the host. Previously the query string leaked into output filenames, which fails on Windows. #197
- [bugfix] OTIO exports use the full source duration when provided, including from the CLI, instead of declaring a fixed 1,980-frame duration. The available range remains unspecified when the duration is unknown. Scene source ranges are unchanged. #580
- [bugfix] The OpenCV backend keeps position on the last frame after reaching the end of a VFR video, so the last scene no longer ends early (or before it starts) #561
- [bugfix] save-html --no-images now writes to the global -o/--output directory instead of the working directory #583
- [bugfix] split-video with -o now logs the output folder instead of repeating the filename template #595
- [bugfix] Allow -d/--downscale on the CLI and downscale in the config file to be set to 0 for automatic downscaling
- [bugfix] save-edl timecodes now count frames at the nominal rate (24, 30, or 60 per timecode second for 23.976, 29.97, or 59.94 fps) as required for non-drop-frame timecode, instead of being derived from wall-clock seconds. Previously the EDL drifted by roughly 3.6 seconds per hour at these rates. --start-timecode is parsed the same way, so -s 01:00:00:00 now starts the first event at 01:00:00:00. Non-standard rates (e.g. the average rate of a VFR video) are unchanged. Thanks to @Cassian433 for the detailed report #593
API Changes
- [feature] VideoStream has a new close() method to release the file handles and decoders a video holds, and can be used as a context manager (with open_video(path) as video:) to close it automatically. Calling close() more than once has no effect. Once an OpenCV, PyAV, MoviePy or concatenated stream is closed, read(), seek() and reset() raise ValueError, while properties describing the video (path, name, frame_rate, duration, frame_size, aspect_ratio) remain available. The default implementation does nothing, so existing VideoStream subclasses are unaffected, and `VideoCaptur
v0.7.2PySceneDetect v0.7.22026-10-12 · 2026-10-12 04:44 UTC
查看更新说明
Release Notes

PySceneDetect 0.7.2 ships improved defaults for the histogram and perceptual hash detectors, adds PyAV 19 support, and fixes several timing and output bugs. Default output of detect-hist and detect-hash will change in this release due to improved default values.

CLI Changes
- [improvement] HistogramDetector (detect-hist) default threshold changed from 0.05 to 0.20 and default bins from 256 to 128, calibrated from the benchmarks. Output for this detector will change if you are not setting both parameters explicitly. #559
  
  Use detect-hist -t 0.05 -b 256 or HistogramDetector(threshold=0.05, bins=256) to restore the previous behavior.
- [improvement] HashDetector (detect-hash) default threshold changed from 0.395 to 0.35 and default size from 16 to 8, calibrated from the benchmarks. Output for this detector will change if you are not setting both parameters explicitly. #559
  
  Use detect-hash -t 0.395 -s 16 or HashDetector(threshold=0.395, size=16) to restore the previous behavior.
- [improvement] detect-threshold now ignores fade-outs shorter than 0.1s by default. Use --min-out-length 0 to restore the previous behavior. The API default remains 0 #278
- [feature] Added save-keyframes command to export detected cuts using # keyframe format v1 for Aegisub-compatible tools #534. Frame numbers are currently approximate for VFR input #569
- [feature] Add --min-out-length/min_out_length to detect-threshold/ThresholdDetector, which requires that fades stay below the threshold for the given duration #278
- [general] -f, --frame-rate, and --framerate are now aliases of the same CLI option, and all forms appear in help and documentation. If multiple forms are given, the last value is used #548
- [bugfix] Progress bar now reaches 100% when processing variable framerate (VFR) videos, with both the OpenCV and PyAV backends #561
- [bugfix] Fix AdaptiveDetector / detect-adaptive emitting scenes shorter than min_scene_len when window_width is large, by applying the minimum-length check to the emitted (target) frame instead of the current frame #408
API Changes
- [api] Legacy framerate argument aliases in FrameTimecode, open_video(), and the video backends now emit a DeprecationWarning; use frame_rate instead. When both forms are provided, frame_rate takes precedence #548
- [api] write_scene_list() now also accepts a path (str or pathlib.Path) as the first argument in addition to an open file handle; paths are opened and closed automatically #523
- [api] Scene-list output functions for EDL, FCPXML, FCP7 XML, and OTIO now accept an open text file handle, a string path, or a pathlib.Path; paths are opened and closed automatically #567
- [bugfix] ThresholdDetector/detect-threshold with method CEILING now classifies the first frame with the CEILING rule instead of the FLOOR rule, which anchored a leading fade one frame late and could emit a spurious cut at the first frame (thanks @MuhammadBilalKhan267)
- [bugfix] Fix min_scene_len given in frames dropping cuts that are exactly min_scene_len frames apart at NTSC frame
v0.7.1PySceneDetect v0.7.12026-07-22 · 2026-07-22 02:49 UTC
查看更新说明
Release Notes

PySceneDetect 0.7.1 adds support for concatenating multiple videos, along with several stability and robustness fixes for the PyAV and OpenCV backends.

CLI Changes
- [feature] split-video has a new --expand flag: when scenes are detected within a time window (-s/-e), the first output clip is extended back to the start of the video and the last clip is extended forward to the end, so no footage outside the analysis window is dropped #115
API Changes
- [feature] scenedetect.detect() now accepts a backend keyword argument ("opencv", "pyav", or "moviepy") similar to open_video. Defaults to "opencv", matching prior behavior.
- [feature] Add expand_scenes_to_bounds() helper in scenedetect.scene_manager to extend a scene list so the first scene starts at a given lower bound and the last scene ends at a given upper bound
- [feature] VideoStream now provides a public read-only decode_failures property reporting the number of frames that failed to decode and were skipped (defaults to 0; populated by the OpenCV and PyAV backends)
- [feature] Add VideoStreamConcat (scenedetect.backends.concat) which concatenates multiple videos into a single continuous stream with a monotonic PTS timeline; open_video() and detect() now accept a list of paths. VideoStreamConcat.map_span() maps spans of the global timeline back to per-source local times
- [bugfix] The PyAV backend (VideoStreamAv) now skips corrupt frames during read() and continues decoding instead of failing, giving up only after 8 consecutive decode failures (matching the OpenCV backend's tolerance behavior)
- [bugfix] The PyAV backend now normalizes presentation times by the stream start time, so files with a delayed start (e.g. from edit lists) report the first frame at position 0, consistent with other backends and with seek()
- [bugfix] Comparisons between two FrameTimecode objects that both carry exact presentation times (e.g. positions from VFR videos) and share the same frame rate are now performed exactly using pts and time_base instead of rounded frame numbers. Previously, distinct frames in VFR sections could compare equal or fail strict ordering when their times rounded to the same approximate frame number. Comparisons involving frame- or seconds-based timecodes, plain values (int/float/str), or differing frame rates are unchanged
- [bugfix] Fix image sequence inputs when using OpenCV 5.0
Packaging
- [general] scenedetect and scenedetect-headless are unchanged: they continue to ship the full program (library + CLI) with opencv-python / opencv-python-headless respectively. Both packages provide the same scenedetect module (install or depend only one)
- [feature] Official Docker images are now published to the GitHub Container Registry with the full CLI, all backends, and external tools (ffmpeg, mkvmerge) included, thanks @FNGarvin #537
  
  Example usage (process a video in the current directory):
```
docker run --rm -v "$(pwd):/files" ghcr.io/breakthrough/pyscenedetect -i /files/video.mp4 detect-adaptive split-video -o /files
```
- [general] The Windows distribution now bundles OpenCV 5.0, PyAV 18, and FFmpeg 8.1.2. The Windows and Docker builds also override Pillow to 12.3.0 for upstream security fixes (moviepy#2553)
General
- [general] Benchmark results are now published on the website (scenedetect.com/benchmarks), including accuracy at default settings and parameter sweep curves for each detector
v0.7-releasePySceneDetect v0.72026-05-03 · 2026-05-03 22:56 UTC
查看更新说明
Release Notes

PySceneDetect 0.7 is a major breaking release which overhauls how timestamps are handled. This allows PySceneDetect to properly process variable framerate (VFR) videos. A significant amount of technical debt has been addressed, including removal of deprecated or overly complicated APIs.

Care was taken to minimize changes for most common API uses, however more advanced use cases may run into breaking changes. Please review the Migration Guide when updating from v0.6. Minimum supported Python version is now Python 3.10.

CLI Changes
- [feature] VFR videos are handled correctly by the OpenCV and PyAV backends, and should work correctly with default parameters
- [feature] All CLI options which used to accept frame numbers only now accept seconds (e.g. 0.6s) and timecodes (e.g. 00:00:00.600) #531
- [feature] New save-fcp command allows exporting in Final Cut Pro format (FCP7/FCPX) #156
- [feature] New save-qp command writes a QP file with scene boundary frame numbers, suitable for forcing keyframes at scene cuts in x264/x265 #448
- [feature] New save-html command replaces the deprecated export-html; the prior command remains as an alias and emits a deprecation warning #518
- [feature] Add save-edl option --start-timecode/-s to providde a custom start timecode for generated EDLs, supports SMPTE HH:MM:SS:FF or 8-digit HHMMSSFF input #515
- [bugfix] Fix floating-point precision error in save-otio output where frame values near integer boundaries (e.g. 90.00000000000001) were serialized with spurious precision
- [bugfix] Add mitigation for transient OSError in the MoviePy backend as it is susceptible to subprocess pipe races on slow or heavily loaded systems #496
- [feature] The MoviePy backend now supports overriding the source frame rate via -f/--frame-rate (and the VideoStreamMoviePy(frame_rate=...) API), bringing it in line with the OpenCV and PyAV backends
- [bugfix] detect-threshold cut frame numbers are now backend-deterministic; previously the cut could differ by 1 frame between PyAV and OpenCV when the fade midpoint landed on a .5 rounding boundary (PyAV uses sub-microsecond PTS, OpenCV uses millisecond-truncated CAP_PROP_POS_MSEC)
- [breaking] Remove deprecated -d/--min-delta-hsv option from detect-adaptive command (use -c/--min-content-val instead)
- [breaking] Rename -f/--framerate to -f/--frame-rate as part of VFR overhaul (legacy --framerate form is preserved as a hidden alias but will be removed in v0.8)
- [general] Support SCENEDETECT_DEBUG environment variable to control how exceptions and debugging are handled. Unhandled exceptions and Ctrl+C now produce a logger-formatted error message and exit cleanly with code 1 instead of dumping a raw Python traceback. Set SCENEDETECT_DEBUG=1 to ensure all exceptions are re-raised instead of being logged. In both cases, the program will exit with a non-zero exit code.
API Changes

VFR & Timestamp Overhaul:
- Add write_scene_list_edl, write_scene_list_fcpx, write_scene_list_fcp7, and write_scene_list_otio to the scenedetect.output module so save-edl, save-fcp, and save-otio can be invoked directly from Python (previously CLI-only)
- write_scene_list_edl accepts an optional start_timecode parameter (SMPTE HH:MM:SS:FF or 8-digit HHMMSSFF) that is added to every event's source and record columns #515
- Add new Timecode type to represent frame timi
v0.6.7-releasePySceneDetect v0.6.72025-08-25 · 2025-08-25 03:37 UTC
查看更新说明
Release Notes

Fixes issues with importing EDL files into DaVinci Resolve and other editors, update ffmpeg.

Changelog
- [bugfix] Fix save-edl end timestamp being too short by 1 frame #516
- [general] Updates to Windows distributions:
  
  ffmpeg 7.1 -> 8.0
v0.6.7.1 (PyPI only, no code changes) - 2025-09-24
- [dist] Fix version pinning to prevent incompatibility with third-party dependencies #521

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

Video Cut Detection and Analysis Tool

Latest Release: v0.7.3 (November 8, 2026)

Website: scenedetect.com

Quickstart Example: scenedetect.com/cli/

Documentation: scenedetect.com/docs/

Discord: https://discord.gg/H83HbJngk7

Quick Install:

pip install scenedetect --upgrade

Requires ffmpeg/mkvmerge for video splitting support. Windows builds (MSI installer/portable ZIP) can be found on the download page. A Docker image with all dependencies included is available as ghcr.io/breakthrough/pyscenedetect.

Quick Start (Command Line):

Split input video on each fast cut using ffmpeg:

scenedetect -i video.mp4 split-video

Save some frames from each cut:

scenedetect -i video.mp4 save-images

Skip the first 10 seconds of the input video:

scenedetect -i video.mp4 time -s 10s

More examples can be found throughout the documentation.

Quick Start (Docker):

The same commands work without installing anything using the official Docker image, 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):

from scenedetect import detect, 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.

Try calling print(scene_list), or iterating over each scene:

from scenedetect import detect, 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,
        )
    )

We can also split the video into each scene if ffmpeg is installed (mkvmerge is also supported):

from scenedetect import detect, ContentDetector, split_video_ffmpeg

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:

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.detect_scenes(video, show_progress=True)
    scene_list = scene_manager.get_scene_list()
    split_video_ffmpeg(video_path, scene_list, show_progress=True)

See the documentation for more examples.

Benchmark:

We evaluate the performance of different detectors in terms of accuracy and processing speed. See www.scenedetect.com/benchmarks for results, or the benchmark report for details on the datasets and methodology.

Reference

Documentation (covers application and Python API)
CLI Example
Config File

Help & Contributing

Please submit any bugs/issues or feature requests to the Issue Tracker. Before submission, ensure you search through existing issues (both open and closed) to avoid creating duplicate entries. Pull requests are welcome and encouraged. PySceneDetect is released under the BSD 3-Clause license, and submitted code should be compliant.

For help or other issues, you can join the official PySceneDetect Discord Server, submit an issue/bug report here on Github, or contact me via my website.

Development Setup

Create a virtual environment and install the project in editable mode with the development dependencies:

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

The tests use videos from the resources branch. Fetch them into tests/resources/ (this folder is ignored by git, so nothing gets staged):

git fetch --depth=1 https://github.com/Breakthrough/PySceneDetect.git resources
git restore --source=FETCH_HEAD tests/resources

Then run pytest. The full test suite also needs ffmpeg and mkvmerge. If ffmpeg is not on your PATH, the copy bundled with imageio-ffmpeg (installed by [dev]) is used instead. Install mkvmerge separately, otherwise its test is skipped.

The editable install provides the scenedetect command (python -m scenedetect also works):

scenedetect -i video.mp4 detect-content list-scenes

Code Signing

This program uses free code signing provided by SignPath.io, and a free code signing certificate by the SignPath Foundation

License

BSD-3-Clause; see LICENSE and THIRD-PARTY.md for details.

怎么上手

项目说明

最近发版

CLI Changes

API Changes

Release Notes

CLI Changes

API Changes

Release Notes

CLI Changes

API Changes

Packaging

General

Release Notes

CLI Changes

API Changes

VFR & Timestamp Overhaul:

Release Notes

Changelog

v0.6.7.1 (PyPI only, no code changes) - 2025-09-24

用户点评

README 原文

Video Cut Detection and Analysis Tool

Latest Release: v0.7.3 (November 8, 2026)

Reference

Help & Contributing

Development Setup

Code Signing

License

相关项目