PySceneDetect Documentation

PySceneDetect provides two primary ways to interact with the tool:

1. Command-Line Interface (CLI): Use the scenedetect command for standalone video analysis and processing.
2. Python API: Import the scenedetect module into your own Python scripts to build custom video analysis workflows.

PySceneDetect detectors are benchmarked against public shot-boundary-detection corpora using the TRECVID-SBD convention. This involves greedy 1-to-1 nearest-neighbor matching for hard cuts (with configurable frame tolerance) and point-in-interval matching for fades.

Key datasets used for benchmarking include:

• BBC Planet Earth: Long-form broadcast episodes (hard cuts only).
• AutoShot: Short-form web/user-generated clips (hard cuts only).
• ClipShots: Short web clips containing both hard cuts and typed gradual transitions.

For detailed raw results and the benchmark harness, refer to the benchmark/ directory in the repository.

Use the high-level scenedetect.detect() function to quickly analyze a video using a specific detector. This returns a list of FrameTimecode pairs representing the start and end of each detected scene. You can pass show_progress=True to display a progress bar.

Common detectors include:

• ContentDetector: Detects fast cuts using weighted average of HSV changes.
• AdaptiveDetector: Finds fast cuts using rolling average of HSL changes.
• ThresholdDetector: Finds fades in/out using average pixel intensity changes in RGB.
• HistogramDetector: Finds fast cuts using HSV histogram changes.
• HashDetector: Finds fast cuts using perceptual image hashing.

from scenedetect import detect, ContentDetector
path = "video.mp4"
scenes = detect(path, ContentDetector())
for (scene_start, scene_end) in scenes:
    print(f"{scene_start}-{scene_end}")

Use the scenedetect command to perform common tasks like splitting video, saving images, or skipping video segments.

• Split video on fast cuts: Uses ffmpeg to split the input.
• Save scene images: Saves frames from each detected cut.
• Skip video duration: Skips a specified amount of time at the start of the video.

The perceptual hash detector (detect-hash) calculates a hash for each frame (using the phash algorithm from the imagehash library) and compares it to the previous frame. If the hashes differ beyond a defined threshold, a scene change is recorded.

Important notes:

• Efficiency: This is generally more computationally efficient than detect-content or detect-adaptive.
• Color Insensitivity: The algorithm converts frames to grayscale, meaning it is insensitive to color changes if the brightness remains constant.

If default parameters do not work, generate a statistics file using the -s or --stats flag. This allows you to analyze frame data to find the optimal threshold.

• For detect-content / detect-adaptive: Examine the content_val column in the stats file. Look for peaks that correspond to known scene changes.
• For detect-threshold: Examine the delta_rgb column (average pixel intensity). The threshold should be set so that scene changes fall under the threshold value.

Benchmark results suggest that optimal parameters vary depending on the content type. Long-form broadcast content (like BBC) generally performs better with lower thresholds than short web clips (like ClipShots).

Below are the best-performing parameters found during mean hard-cut F1 sweeps across all datasets:

Note: The v0.7 defaults may differ from these optimal values.

Comprehensive documentation for PySceneDetect can be found at the official website:

https://www.scenedetect.com/docs