PySceneDetect
Open-source Python library and command-line tool that detects shot changes in videos and can split them into separate clips.
At a Glance
PySceneDetect is free and open-source software licensed under BSD 3-Clause.
Engagement
Available On
Alternatives
Listed Nov 2026
About PySceneDetect
PySceneDetect is a free, open-source tool and Python library by Brandon Castellano for detecting shot changes in video and automatically splitting footage into separate clips. It is built on Python and OpenCV and is available through a command-line interface, a Python API, and an official Docker image. The latest release listed is v0.7.3.
What It Is
PySceneDetect analyzes a video file to find cuts (fast transitions) and fades, then outputs a list of scenes with start and end timecodes and frame numbers. If ffmpeg or mkvmerge is available, it can split the input video into one clip per detected scene. The default timecode format (HH:MM:SS.nnn) is designed to be pasted directly into tools such as ffmpeg or the mkvtoolnix suite.
Detection Methods and Outputs
Several detectors can be used independently or combined: adaptive content detection (rolling average of HSL differences), content detection (HSL differences), perceptual hash detection, histogram detection on the Y channel, and threshold detection for fade in/out. Each is configurable. Results can be saved as images of scene frames, FFmetadata chapters, CMX 3600 EDL files, HTML tables, OpenTimelineIO files, or x264 QP files. A statistics mode exports frame-by-frame metrics to CSV to help tune thresholds.
Setup Path
Install with pip, use the Windows MSI installer or portable ZIP, or run the Docker image that bundles ffmpeg and mkvmerge. The Python API offers a high-level detect function and a SceneManager for custom pipelines. The project documents uses such as splitting source footage, removing commercials from PVR recordings, processing surveillance footage, finding loops for GIFs, and academic film analysis.
Community Discussions
Be the first to start a conversation about PySceneDetect
Share your experience with PySceneDetect, ask questions, or help others learn from your insights.
Pricing
Open Source
PySceneDetect is free and open-source software licensed under BSD 3-Clause.
- BSD 3-Clause license
- Command-line tool and Python API
- Multiple detection methods (content, adaptive, threshold)
- Split video into clips using ffmpeg or mkvmerge
- Docker image available
Capabilities
Key Features
- Content-aware shot change detection
- Adaptive, content, hash, histogram and threshold detectors
- Automatic video splitting via ffmpeg or mkvmerge
- Export to chapters, EDL, HTML, OTIO and QP formats
- Save first and last frame images of each scene
- Statistics CSV export for frame-by-frame metrics
- Quiet mode for automation
- Python API for custom detection pipelines
- Official Docker image
- Benchmarks on public shot-boundary datasets
