diff --git a/docs/api.rst b/docs/api.rst index 4d65f493..5278aad0 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,17 +3,23 @@ ``scenedetect`` 🎬 Package *********************************************************************** -The `scenedetect` API is easy to integrate with most application workflows, while also being highly extensible. See the `Quickstart`_ and `Example`_ sections below for some common use cases and integrations. The `scenedetect` package contains several modules: +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 changes/cuts in video content. + * :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:`ThresholdDetector `: detects changes in video brightness/intensity. + * :mod:`HistogramDetector ` finds fast cuts using HSV histogram changes - * :mod:`AdaptiveDetector `: similar to `ContentDetector` but may result in less false negatives during rapid camera movement. + * :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`: @@ -30,7 +36,7 @@ The `scenedetect` API is easy to integrate with most application workflows, whil * :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. Also used as a persistent cache to make multiple passes on the same video significantly faster. + * :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. @@ -49,38 +55,33 @@ Most types/functions are also available directly from the `scenedetect` package .. _scenedetect-quickstart: ======================================================================= -Examples +Getting Started ======================================================================= -To get started, the :func:`scenedetect.detect` function takes a path to a video and a :ref:`scene detector object`, and returns a list of start/end timecodes. For detecting fast cuts (shot changes), we use the :class:`ContentDetector `: +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 - scene_list = detect("my_video.mp4", ContentDetector()) + path = "video.mp4" + scenes = detect(path, ContentDetector()) + for (scene_start, scene_end) in scenes: + print(f'{scene_start}-{scene_end}') -``scene_list`` is now a list of :class:`FrameTimecode ` pairs representing the start/end of each scene (try calling ``print(scene_list)``). Note that you can set ``show_progress=True`` when calling :func:`detect ` to display a progress bar with estimated time remaining. +``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. -Next, let's print the scene list in a more readable format by iterating over it: - -.. code:: python - - for i, scene in enumerate(scene_list): - print("Scene %2d: Start %s / Frame %d, End %s / Frame %d" % ( - i+1, - scene[0].get_timecode(), scene[0].get_frames(), - scene[1].get_timecode(), scene[1].get_frames(),)) - -Now that we know where each scene is, we can also :ref:`split the input video ` automatically using `ffmpeg` (`mkvmerge` is also supported): +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", scene_list) + 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 ======================================================================= @@ -106,6 +107,7 @@ Module Reference api/scene_detector api/video_stream api/platform + api/migration_guide ======================================================================= diff --git a/docs/api/migration_guide.rst b/docs/api/migration_guide.rst index 7f7df42e..11da142a 100644 --- a/docs/api/migration_guide.rst +++ b/docs/api/migration_guide.rst @@ -5,7 +5,7 @@ Migration Guide --------------------------------------------------------------- -This page details how to transition a program written using PySceneDetect 0.5 to the new 0.6 API. It is recommended to review the new :ref:`Example ` section first, as it covers the majority of use cases. Also see `tests/test_api.py `_ for a set of demonstrations covering many high level use cases. +This page details how to transition a program written using PySceneDetect 0.5 to the new 0.6 API. It is recommended to review the new :ref:`Example ` section first, as it covers the majority of use cases. Also see `tests/test_api.py `_ for a set of demonstrations covering many high level use cases. PySceneDetect v0.6 is a major step towards a more stable and simplified API. The biggest change to existing workflows is how video input is handled, and that Python 3.6 or above is now required. diff --git a/docs/index.rst b/docs/index.rst index 7e820574..1aca59b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,7 +54,6 @@ Table of Contents api/scene_detector api/video_stream api/platform - api/migration_guide ======================================================================= Indices and Tables diff --git a/scenedetect/scene_manager.py b/scenedetect/scene_manager.py index dc3bba04..c3508b0b 100644 --- a/scenedetect/scene_manager.py +++ b/scenedetect/scene_manager.py @@ -1086,6 +1086,8 @@ def get_cut_list( List of FrameTimecode objects denoting the points in time where a scene change was detected in the input video, which can also be passed to external tools for automated splitting of the input into individual scenes. + + :meta private: """ # TODO(v0.7): Use the warnings module to turn this into a warning. if show_warning: @@ -1108,6 +1110,8 @@ def get_event_list( Returns: List of pairs of FrameTimecode objects denoting the detected scenes. + + :meta private: """ # TODO(v0.7): Use the warnings module to turn this into a warning. logger.error("`get_event_list()` is deprecated and will be removed in a future release.") diff --git a/scenedetect/stats_manager.py b/scenedetect/stats_manager.py index b028e244..d32fe0bf 100644 --- a/scenedetect/stats_manager.py +++ b/scenedetect/stats_manager.py @@ -49,13 +49,19 @@ class FrameMetricRegistered(Exception): - """[DEPRECATED - DO NOT USE] No longer used.""" + """[DEPRECATED - DO NOT USE] No longer used. + + :meta private: + """ pass class FrameMetricNotRegistered(Exception): - """[DEPRECATED - DO NOT USE] No longer used.""" + """[DEPRECATED - DO NOT USE] No longer used. + + :meta private: + """ pass @@ -236,6 +242,8 @@ def load_from_csv(self, csv_file: Union[str, bytes, TextIO]) -> Optional[int]: Raises: StatsFileCorrupt: Stats file is corrupt and can't be loaded, or wrong file was specified. + + :meta private: """ # TODO: Make this an error, then make load_from_csv() a no-op, and finally, remove it. logger.warning("load_from_csv() is deprecated and will be removed in a future release.") diff --git a/scenedetect/video_splitter.py b/scenedetect/video_splitter.py index 8b41834d..2ee95527 100644 --- a/scenedetect/video_splitter.py +++ b/scenedetect/video_splitter.py @@ -174,7 +174,7 @@ def split_video_mkvmerge( is supported by this function. video_name (str): Name of the video to be substituted in output_file_template for $VIDEO_NAME. If not specified, will be obtained from the filename. - show_output: If False, adds the --quiet flag when invoking `mkvmerge`.. + show_output: If False, adds the --quiet flag when invoking `mkvmerge`. suppress_output: [DEPRECATED] DO NOT USE. For backwards compatibility only. Returns: Return code of invoking mkvmerge (0 on success). If scene_list is empty, will