*********************************************************************** ``scenedetect`` 🎬 Package *********************************************************************** The `scenedetect` API is easy to integrate with most application workflows, while also being highly extensible. See the `Getting Started`_ section below for some common use cases and integrations. The `scenedetect` package contains several modules: * :ref:`scenedetect 🎬 `: Includes the :func:`scenedetect.detect ` function which takes a path and a :ref:`detector ` to find scene transitions (:ref:`example `), and :func:`scenedetect.open_video ` for video input * :ref:`scenedetect.scene_manager 🎞️ `: The :class:`SceneManager ` acts as a way to coordinate detecting scenes (via `SceneDetector` instances) on video frames (via :ref:`VideoStream ` instances). This module also contains functionality to export information about scenes in various formats: :func:`save_images ` to save images for each scene, :func:`write_scene_list ` to save scene/cut info as CSV, and :func:`write_scene_list_html ` to export scenes in viewable HTML format. * :ref:`scenedetect.detectors 🕵️ `: Detection algorithms: * :mod:`ContentDetector `: detects fast cuts using weighted average of HSV changes * :mod:`ThresholdDetector `: finds fades in/out using average pixel intensity changes in RGB * :mod:`AdaptiveDetector ` finds fast cuts using rolling average of HSL changes * :mod:`HistogramDetector ` finds fast cuts using HSV histogram changes * :mod:`HashDetector `: finds fast cuts using perceptual image hashing * :ref:`scenedetect.video_stream 🎥 `: Video input is handled through the :class:`VideoStream ` interface. Implementations for common video libraries are provided in :mod:`scenedetect.backends`: * OpenCV: :class:`VideoStreamCv2 ` * PyAV: :class:`VideoStreamAv ` * MoviePy: :class:`VideoStreamMoviePy ` * :ref:`scenedetect.video_splitter ✂️ `: Contains :func:`split_video_ffmpeg ` and :func:`split_video_mkvmerge ` to split a video based on the detected scenes. * :ref:`scenedetect.frame_timecode ⏱️ `: Contains :class:`FrameTimecode ` class for storing, converting, and performing arithmetic on timecodes with frame-accurate precision. * :ref:`scenedetect.scene_detector 🌐 `: Contains :class:`SceneDetector ` interface which detection algorithms must implement. * :ref:`scenedetect.stats_manager 🧮 `: Contains :class:`StatsManager ` class for caching frame metrics and loading/saving them to disk in CSV format for analysis. * :ref:`scenedetect.platform 🐱‍💻 `: Logging and utility functions. Most types/functions are also available directly from the `scenedetect` package to make imports simpler. .. warning:: The PySceneDetect API is still under development. It is recommended that you pin the `scenedetect` version in your requirements to below the next major release: .. code:: python scenedetect<0.7 .. _scenedetect-quickstart: ======================================================================= Getting Started ======================================================================= PySceneDetect makes it very easy to find scene transitions in a video with the :func:`scenedetect.detect` function: .. code:: python 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}') ``scenes`` now contains a list of :class:`FrameTimecode ` pairs representing the start/end of each scene. Note that you can set ``show_progress=True`` when calling :func:`detect ` to display a progress bar with estimated time remaining. Here, we use :mod:`ContentDetector ` to detect fast cuts. There are :ref:`many detector types ` which can be used to find fast cuts and fades in/out. PySceneDetect can also export scene data in various formats, and can :ref:`split the input video ` automatically if `ffmpeg` is available: .. code:: python from scenedetect import detect, ContentDetector, split_video_ffmpeg scene_list = detect("my_video.mp4", ContentDetector()) split_video_ffmpeg("my_video.mp4", scenes) Recipes for common use cases can be `found on Github `_ including limiting detection time and storing per-frame metrics. For advanced workflows, start with the :ref:`SceneManager usage examples `. .. _scenedetect-functions: ======================================================================= Functions ======================================================================= .. automodule:: scenedetect :members: ======================================================================= Module Reference ======================================================================= .. toctree:: :maxdepth: 3 :caption: PySceneDetect Module Documentation :name: fullapitoc api/detectors api/backends api/scene_manager api/video_splitter api/stats_manager api/frame_timecode api/scene_detector api/video_stream api/platform api/migration_guide ======================================================================= Logging ======================================================================= PySceneDetect outputs messages to a logger named ``pyscenedetect`` which does not have any default handlers. You can use :func:`scenedetect.init_logger ` with ``show_stdout=True`` or specify a log file (verbosity can also be specified) to attach some common handlers, or use ``logging.getLogger("pyscenedetect")`` and attach log handlers manually. ======================================================================= Migrating From 0.5 ======================================================================= PySceneDetect 0.6 introduces several breaking changes which are incompatible with 0.5. See :ref:`Migration Guide ` for details on how to update your application. In addition, demonstrations of common use cases can be found in the `tests/test_api.py `_ file.