See the API Overview page of the manual for an overview of PySceneDetect's module & class layout. There are three main modules:
scenedetect- main functionality, has imports for commonly used classes and detection algorithms
scenedetect.detectors- scene detection algorithms
scenedetect.cli- command-line specific functionality
Classes from main
FrameTimecode- used to store timecodes as well as perform arithmetic on timecode values (addition/subtraction/comparison) with frame-accurate precision
SceneManager- high-level manager to coordinate SceneDetector, VideoManager, and optionally, StatsManager objects
VideoManager- used to load video(s) and provide seeking
StatsManager- used to store/cache frame metrics to speed up subsequent scene detection runs on the same video, and optionally, save/load to/from a CSV file
SceneDetector- base class used to implement detection algorithms (e.g.
SceneDetector objects available in the
ThresholdDetector- detects fade-outs/fade-ins to/from black by looking at the intensity/brightness of the video
ContentDetector- detects scene cuts/content changes by converting the video to the HSV colourspace
All functions are well documented with complete docstrs, and documentation can be found by calling help() from a Python REPL or browsing the complete PySceneDetect v0.5 API Reference below. Also note that auto-generated documentation (via the
pydoc command/module) can be generated.
The complete PySceneDetect Python API reference can be found here (link)..
Using PySceneDetect from Python
PySceneDetect can also be used from within other Python programs, or even the Python REPL itself. PySceneDetect allows you to perform scene detection on a video file, yielding a list of scene cuts/breaks at the exact frame number where the scene boundaries occur.
The general usage workflow is to determine which detection method and threshold to use (this can even be done iteratively), using these values to create a
SceneDetector object, the type of which depends on the detection method you want to use (e.g.
ContentDetector). A list of
SceneDetector objects is then passed with an open
VideoCapture object and an empty list to the
scenedetect.detect_scenes() function, which appends the frame numbers of any detected scene boundaries to the list (the function itself returns the number of frames read from the video file).
In the code example below, we create a function
find_scenes() which will
load a video, detect the scenes, and return a list of tuples containing the
(start, end) timecodes of each detected scene. Note that you can modify
threshold argument to modify the sensitivity of the scene detection.
# Standard PySceneDetect imports: from scenedetect import VideoManager from scenedetect import SceneManager # For content-aware scene detection: from scenedetect.detectors import ContentDetector def find_scenes(video_path, threshold=30.0): # Create our video & scene managers, then add the detector. video_manager = VideoManager([video_path]) scene_manager = SceneManager() scene_manager.add_detector( ContentDetector(threshold=threshold)) # Base timestamp at frame 0 (required to obtain the scene list). base_timecode = video_manager.get_base_timecode() # Improve processing speed by downscaling before processing. video_manager.set_downscale_factor() # Start the video manager and perform the scene detection. video_manager.start() scene_manager.detect_scenes(frame_source=video_manager) # Each returned scene is a tuple of the (start, end) timecode. return scene_manager.get_scene_list(base_timecode)
The scene list returned by the
SceneManager.get_scene_list(...) method consists of the start and (one past) the end frame of each scene, in the form of a
FrameTimecode object. Each
FrameTimecode can be converted to the appropriate working/output format via the
get_sceonds() methods as shown above; see the API documentation for
FrameTimecode objects for details.
For a more advanced example, see the
api_test.py file in the
tests folder which illustrates the general workflow and usage of the
scenedetect module to perform scene detection programmatically. It provides a good example as to the general usage of the PySceneDetect Python API for detecting the scenes on an input video and printing the scenes to the terminal/console.