About
PySceneDetect is a powerful open-source library and command-line tool designed to detect scene changes and shot boundaries in video files. It supports two primary detection approaches: content-aware detection for fast cuts and threshold-based detection for fade-in/fade-out transitions. Once scenes are identified, PySceneDetect can automatically split the source video into individual clips using FFmpeg or mkvtoolnix under the hood. The tool offers two primary interfaces: a command-line tool for quick one-off tasks and a full Python API for integration into custom scripts or automated processing pipelines. The timecode output format (HH:MM:SS.nnnn) is compatible with widely-used video tools like ffmpeg, avconv, and the MKVToolNix suite, making it easy to pass results into downstream workflows. PySceneDetect is used across a wide range of domains. Video editors and content creators use it to break long recordings into manageable clips. Developers and researchers apply it for statistical film analysis, commercial detection in PVR recordings, surveillance footage segmentation, and identifying loop-able segments for animated GIFs. Academics leverage it for computational film studies, such as calculating mean shot lengths across a corpus of films. Licensed under the BSD 3-Clause license, PySceneDetect is cross-platform and runs on Windows, macOS, and Linux. It is actively maintained and well-documented, with a growing community of contributors. Whether you are a developer building a video processing pipeline or a content creator automating repetitive editing tasks, PySceneDetect provides a reliable and flexible foundation.
Key Features
- Automated Scene Detection: Detects shot boundaries and scene changes in video files using content-aware and threshold-based algorithms.
- Multiple Detection Methods: Supports fast-cut detection via the AdaptiveDetector and threshold-based fade detection to handle a wide range of editing styles.
- Automatic Video Splitting: Splits source video files into individual scene clips automatically using FFmpeg or mkvtoolnix integration.
- Python API: Provides a full-featured Python library for embedding scene detection into custom scripts, automation pipelines, or research workflows.
- Command-Line Interface: Includes a powerful CLI for quick scene detection and splitting without writing any code.
Use Cases
- Splitting long home videos or raw footage recordings into individual scenes for easier editing
- Automatically detecting and removing commercials from PVR-recorded television content
- Segmenting surveillance camera footage into discrete event clips for review or archiving
- Finding repeating or loopable segments in video for use in animated GIFs or cinemagraphs
- Academic and computational film analysis, such as measuring mean shot length across a film dataset
Pros
- Completely Free and Open Source: Licensed under BSD 3-Clause, PySceneDetect is free to use, modify, and distribute in both personal and commercial projects.
- Flexible Access via CLI and Python API: Supports both command-line usage for quick tasks and a Python API for deep integration into automated workflows.
- Broad Compatibility: Outputs timecodes in a format compatible with ffmpeg, avconv, and MKVToolNix, making it easy to use alongside other video tools.
- Cross-Platform Support: Runs natively on Windows, macOS, and Linux with no platform-specific limitations.
Cons
- No Graphical User Interface: PySceneDetect is CLI and API only — users who prefer a GUI will need to use a separate video editing application.
- Requires FFmpeg for Video Splitting: Automatic video splitting depends on an external FFmpeg installation, adding a setup step for new users.
- Learning Curve for Non-Developers: Using the Python API or tuning detection parameters requires familiarity with Python or command-line tools.
Frequently Asked Questions
What is PySceneDetect?
PySceneDetect is a free, open-source tool for automatically detecting scene changes and shot boundaries in video files. It can also split the video into individual clips based on detected scenes.
How do I use PySceneDetect?
You can use it via the command line (e.g., `scenedetect -i video.mp4 split-video`) or through its Python API by importing modules like `detect` and `AdaptiveDetector` from the `scenedetect` package.
Does PySceneDetect support all video formats?
PySceneDetect supports any video format that your installed version of FFmpeg supports, which covers most common formats including MP4, MKV, AVI, and MOV.
Is PySceneDetect free to use commercially?
Yes, PySceneDetect is licensed under the BSD 3-Clause license, which permits free use in both personal and commercial projects with minimal restrictions.
What detection methods are available?
PySceneDetect offers content-aware detection for fast cuts (using the AdaptiveDetector) and threshold-based detection for fade-in/fade-out transitions, among other available detectors documented in the Python API reference.
