Overview

  Content-Aware Scene Detection

    Detects breaks in-between content, not only when the video fades to black (although a threshold mode is available as well for those cases).

  Compatible With Many External Tools

    The detected scene boundaries/cuts can be exported in a variety of formats, with the default type (comma-separated HH:MM:SS.nnn values) being ready to copy-and-paste directly into other tools (such as ffmpeg, mkvmerge, etc...) for splitting and/or re-encoding the video.

  Statistical Video Analysis

    Can output a spreadsheet-compatible file for analyzing trends in a particular video file, to determine the optimal threshold values to use with specific scene detection methods/algorithms.

  Extendible and Embeddable

    Written in Python, and designed with an easy-to-use and extendable API, PySceneDetect is ideal for embedding into other programs, or to implement custom methods/algorithms of scene detection for specific applications (e.g. analyzing security camera footage).

Features

  • exports list of scenes to .CSV file and terminal (both timecodes and frame numbers) with list-scenes command
  • exports timecodes in standard format (HH:MM:SS.nnn), comma-separated for easy copy-and-paste into external tools and analysis with spreadsheet software
  • statistics/analysis mode to export frame-by-frame video metrics via the -s [FILE]/--stats [FILE] argument (e.g. --stats metrics.csv)
  • output-suppression (quiet) mode for better automation with external scripts/programs (-q/--quiet)
  • save an image of the first and last frame of each detected scene via the save-images command
  • split the input video automatically if ffmpeg or mkvmerge is available via the split-video command

Detection Methods

PySceneDetect implements a variety of different detection algorithms which can be used independently or combined depending on the source material being analyzed.

  • adaptive content scene detection (detect-adaptive): uses rolling average of differences in HSL colorspace combined with thresholding to detect shot changes (fast cut)
  • content-aware scene detection (detect-content): uses differences in HSL colorspace combined with filtering to detect shot changes (fast cut)
  • content-aware scene detection (detect-hash): uses perceptual hashing to determine differences between frames to find shot changes (fast cut)
  • content-aware scene detection (detect-hist): uses differences in histograms of Y channel of frames after conversion to YUV (fast cut)
  • threshold scene detection (detect-threshold): uses average frame intensity (brightness) to detect slow transitions (fade in/out)

By default, detection methods are tuned to provide high performance during processing, while maintaining reasonable accuracy. Each detection method is configurable, and different parameters can be changed for specific use cases. See the documentation for details.

Version Roadmap

Future version roadmaps are now tracked as milestones (link). Specific issues/features that are queued up for the very next release will have the backlog tag, and issues/features being worked on will have the status: in progress tag. Also note that bug reports as well as additional feature requests can be submitted via the issue tracker; read the Bug Reports and Contributing page for details.

Planned Features

The following features are under consideration for future releases. Any contributions towards completing these features are most welcome (pull requests may be accpeted via Github).

  • graphical interface (GUI)
  • automatic threshold detection for the current scene detection methods (or just output message indicating "Predicted Threshold: X")
  • suppression of short-length flashes/bursts of light #35
  • histogram-based detection algorithm in HSV/HSL color space #53
  • perceptual hash based scene detection (prototype by @wjs018 in PR#290)
  • adaptive bias for fade in/out interpolation
  • export scenes in chapter/XML format #323