[docs] Reorganize docs for 0.7

Place things in a more natural order and reduce verbosity to make it easier to identify what each module does.

Author: Breakthrough

docs/api.rst

@@ -3,13 +3,11 @@
 ``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:
+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 is organized into several sub-modules:
 
-    * :ref:`scenedetect 🎬 <scenedetect-functions>`: Includes the :func:`scenedetect.detect <scenedetect.detect>` function which takes a path and a  :ref:`detector <scenedetect-detectors>` to find scene transitions (:ref:`example <scenedetect-quickstart>`), and :func:`scenedetect.open_video <scenedetect.open_video>` for video input
+    * :ref:`scenedetect 🎬 <scenedetect-functions>`: high-level functions like :func:`scenedetect.detect() <scenedetect.detect>` to quickly analyze a video with any :ref:`detection algorithm <scenedetect-detectors>` (:ref:`example <scenedetect-quickstart>`) and get a list of timecode pairs as a result
 
-    * :ref:`scenedetect.scene_manager 🎞️ <scenedetect-scene_manager>`: The :class:`SceneManager <scenedetect.scene_manager.SceneManager>` acts as a way to coordinate detecting scenes (via `SceneDetector` instances) on video frames (via :ref:`VideoStream <scenedetect-video_stream>` instances).
-
-    * :ref:`scenedetect.detectors 🕵️ <scenedetect-detectors>`: Detection algorithms:
+    * :ref:`scenedetect.detectors 🕵️ <scenedetect-detectors>`: detection algorithms:
 
         * :mod:`ContentDetector <scenedetect.detectors.content_detector>`: detects fast cuts using weighted average of HSV changes
 
@@ -21,27 +19,33 @@ The `scenedetect` API is easy to integrate with most application workflows, whil
 
         * :mod:`HashDetector <scenedetect.detectors.hash_detector>`: finds fast cuts using perceptual image hashing
 
-    * :ref:`scenedetect.video_stream 🎥 <scenedetect-video_stream>`: Video input is handled through the :class:`VideoStream <scenedetect.video_stream.VideoStream>` interface. Implementations for common video libraries are provided in :mod:`scenedetect.backends`:
-
-        * OpenCV: :class:`VideoStreamCv2 <scenedetect.backends.opencv.ideoStreamCv2>`
-        * PyAV: :class:`VideoStreamAv <scenedetect.backends.pyav.VideoStreamAv>`
-        * MoviePy: :class:`VideoStreamMoviePy <scenedetect.backends.moviepy.VideoStreamMoviePy>`
-
-     * :ref:`scenedetect.output ✂️ <scenedetect-output>`: Output formats:
+    * :ref:`scenedetect.output ✂️ <scenedetect-output>`: Output formats:
 
         * :func:`split_video_ffmpeg <scenedetect.output.split_video_ffmpeg>` and :func:`split_video_mkvmerge <scenedetect.output.split_video_mkvmerge>` split a video based on the detected scenes
 
         * :func:`save_images <scenedetect.scene_manager.save_images>` can save an arbitrary number of images from each scene
 
         * :func:`write_scene_list <scenedetect.scene_manager.write_scene_list>` can be used to save scene/cut info as CSV, :func:`write_scene_list_html <scenedetect.scene_manager.write_scene_list_html>` for HTML
 
-    * :ref:`scenedetect.common ⏱️ <scenedetect-common>`: Contains common types such as :class:`FrameTimecode <scenedetect.common.FrameTimecode>` used for timecode handing.
+    * :ref:`scenedetect.backends 🎥 <scenedetect-backends>`: PySceneDetect supports multiple libraries as an input backend:
+
+        * OpenCV: :class:`VideoStreamCv2 <scenedetect.backends.opencv.ideoStreamCv2>`
+
+        * PyAV: :class:`VideoStreamAv <scenedetect.backends.pyav.VideoStreamAv>`
+
+        * MoviePy: :class:`VideoStreamMoviePy <scenedetect.backends.moviepy.VideoStreamMoviePy>`
+
+    * :ref:`scenedetect.common ⏱️ <scenedetect-common>`: common functionality such as :class:`FrameTimecode <scenedetect.common.FrameTimecode>` for timecode handling
+
+    * :ref:`scenedetect.scene_manager 🎞️ <scenedetect-scene_manager>`: the :class:`SceneManager <scenedetect.scene_manager.SceneManager>` coordinates performing scene detection on a video with one or more detectors
+
+    * :ref:`scenedetect.detector 🌐 <scenedetect-detector>`: the interface (:class:`SceneDetector <scenedetect.detector.SceneDetector>`) that detectors must implement to be compatible with PySceneDetect
 
-    * :ref:`scenedetect.detector 🌐 <scenedetect-detector>`: Contains :class:`SceneDetector <scenedetect.detector.SceneDetector>` interface which detection algorithms must implement.
+    * :ref:`scenedetect.video_stream  <scenedetect-video_stream>`: the interface (:class:`VideoStream <scenedetect.video_stream.VideoStream>`) that detectors must implement to be compatible with PySceneDetect
 
-    * :ref:`scenedetect.stats_manager 🧮 <scenedetect-stats_manager>`: Contains :class:`StatsManager <scenedetect.stats_manager.StatsManager>` class for caching frame metrics and loading/saving them to disk in CSV format for analysis.
+    * :ref:`scenedetect.stats_manager 🧮 <scenedetect-stats_manager>`: the :class:`StatsManager <scenedetect.stats_manager.StatsManager>` allows you to store detection metrics for each frame and save them to CSV for further analysis
 
-    * :ref:`scenedetect.platform 🐱‍💻 <scenedetect-platform>`: Logging and utility functions.
+    * :ref:`scenedetect.platform 🐱‍💻 <scenedetect-platform>`: logging and utility functions
 
 
 Most types/functions are also available directly from the `scenedetect` package to make imports simpler.

docs/api/output.rst

@@ -6,10 +6,23 @@
 Ouptut
 -------------------------------------------------
 
-.. automodule:: scenedetect.output
-   :members:
-
 .. autofunction:: scenedetect.output.save_images
 
-.. automodule:: scenedetect.output.video
-   :members:
+.. autofunction:: scenedetect.output.is_ffmpeg_available
+
+.. autofunction:: scenedetect.output.split_video_ffmpeg
+
+.. autofunction:: scenedetect.output.is_mkvmerge_available
+
+.. autofunction:: scenedetect.output.split_video_mkvmerge
+
+.. autofunction:: scenedetect.output.write_scene_list_html
+
+.. autofunction:: scenedetect.output.write_scene_list
+
+.. autoclass:: scenedetect.output.SceneMetadata
+
+.. autoclass:: scenedetect.output.VideoMetadata
+
+.. autofunction:: scenedetect.output.default_formatter
+

docs/index.rst

@@ -46,13 +46,13 @@ Table of Contents
 
     api
     api/detectors
-    api/scene_manager
-    api/common
-    api/backends
     api/output
-    api/stats_manager
+    api/backends
+    api/common
+    api/scene_manager
     api/detector
     api/video_stream
+    api/stats_manager
     api/platform
 
 =======================================================================

scenedetect/_cli/config.py

@@ -28,7 +28,7 @@
 from scenedetect.common import FrameTimecode
 from scenedetect.detector import FlashFilter
 from scenedetect.detectors import ContentDetector
-from scenedetect.output.video import DEFAULT_FFMPEG_ARGS
+from scenedetect.output.video import _DEFAULT_FFMPEG_ARGS
 from scenedetect.scene_manager import Interpolation
 
 PYAV_THREADING_MODES = ["NONE", "SLICE", "FRAME", "AUTO"]
@@ -441,7 +441,7 @@ class XmlFormat(Enum):
         "output": None,
     },
     "split-video": {
-        "args": DEFAULT_FFMPEG_ARGS,
+        "args": _DEFAULT_FFMPEG_ARGS,
         "copy": False,
         "filename": "$VIDEO_NAME-Scene-$SCENE_NUMBER",
         "high-quality": False,

scenedetect/output/video.py

@@ -43,7 +43,7 @@
 
 logger = logging.getLogger("pyscenedetect")
 
-COMMAND_TOO_LONG_STRING = """
+_COMMAND_TOO_LONG_STRING = """
 Cannot split video due to too many scenes (resulting command
 is too large to process). To work around this issue, you can
 split the video manually by exporting a list of cuts with the
@@ -52,10 +52,10 @@
 for details.  Sorry about that!
 """
 
-FFMPEG_PATH: ty.Optional[str] = get_ffmpeg_path()
+_FFMPEG_PATH: ty.Optional[str] = get_ffmpeg_path()
 """Relative path to the ffmpeg binary on this system, if any (will be None if not available)."""
 
-DEFAULT_FFMPEG_ARGS = (
+_DEFAULT_FFMPEG_ARGS = (
     "-map 0:v:0 -map 0:a? -map 0:s? -c:v libx264 -preset veryfast -crf 22 -c:a aac"
 )
 """Default arguments passed to ffmpeg when invoking the `split_video_ffmpeg` function."""
@@ -87,7 +87,7 @@ def is_ffmpeg_available() -> bool:
     Returns:
         True if `ffmpeg` can be invoked, False otherwise.
     """
-    return FFMPEG_PATH is not None
+    return _FFMPEG_PATH is not None
 
 
 ##
@@ -232,7 +232,7 @@ def split_video_mkvmerge(
                 float(total_frames) / (time.time() - processing_start_time),
             )
     except CommandTooLong:
-        logger.error(COMMAND_TOO_LONG_STRING)
+        logger.error(_COMMAND_TOO_LONG_STRING)
     except OSError:
         logger.error(
             "mkvmerge could not be found on the system."
@@ -249,7 +249,7 @@ def split_video_ffmpeg(
     output_dir: ty.Optional[Path] = None,
     output_file_template: str = "$VIDEO_NAME-Scene-$SCENE_NUMBER.mp4",
     video_name: ty.Optional[str] = None,
-    arg_override: str = DEFAULT_FFMPEG_ARGS,
+    arg_override: str = _DEFAULT_FFMPEG_ARGS,
     show_progress: bool = False,
     show_output: bool = False,
     suppress_output=None,
@@ -329,7 +329,7 @@ def split_video_ffmpeg(
             output_path.parent.mkdir(parents=True, exist_ok=True)
 
             # Gracefully handle case where FFMPEG_PATH might be unset.
-            call_list = [FFMPEG_PATH if FFMPEG_PATH is not None else "ffmpeg"]
+            call_list = [_FFMPEG_PATH if _FFMPEG_PATH is not None else "ffmpeg"]
             if not show_output:
                 call_list += ["-v", "quiet"]
             elif i > 0:
@@ -371,7 +371,7 @@ def split_video_ffmpeg(
             )
 
     except CommandTooLong:
-        logger.error(COMMAND_TOO_LONG_STRING)
+        logger.error(_COMMAND_TOO_LONG_STRING)
     except OSError:
         logger.error(
             "ffmpeg could not be found on the system."