Merge branch 'main' into develop

Breakthrough · Breakthrough · commit ea0d18f3a620 · 2024-04-27T17:26:04.000-04:00
diff --git a/.github/workflows/build-windows.yml b/.github/workflows/build-windows.yml
@@ -31,10 +31,10 @@ jobs:
         python-version: ["3.9"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
@@ -95,7 +95,7 @@ jobs:
     runs-on: windows-latest
     needs: build
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: resources
 
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -27,22 +27,27 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-20.04, ubuntu-latest, windows-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        # TODO(1.6.1): Deprecate Python 3.7 and support macos-14.
+        os: [macos-13, ubuntu-20.04, ubuntu-latest, windows-latest]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    env:
+      # Version is extracted below and used to find correct package install path.
+      scenedetect_version: ""
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
 
       - name: Install Dependencies
-        # TODO: `setuptools` is pinned for the Python 3.7 builder and can be unpinned when removed.
+        # TODO(1.6.1): Unpin the following requirements when deprecating the Python 3.7 builder.
         run: |
-          python -m pip install --upgrade pip build wheel virtualenv setuptools==62.3.4
+          python -m pip install --upgrade pip build==1.1.1 wheel====0.42.0 virtualenv setuptools==62.3.4
           pip install av opencv-python-headless --only-binary :all:
           pip install -r requirements_headless.txt
 
@@ -84,15 +89,13 @@ jobs:
           git mv docs docs_src
           sphinx-build -b singlehtml docs_src docs
 
-      # TODO: Make the version extraction work on powershell so package smoke tests can run on Windows.
       - name: Build Package
-        if: ${{ matrix.os != 'windows-latest' }}
+        shell: bash
         run: |
           python -m build
           echo "scenedetect_version=`python -c \"import scenedetect; print(scenedetect.__version__.replace('-', '.'))\"`" >> "$GITHUB_ENV"
 
       - name: Smoke Test Package (Source Dist)
-        if: ${{ matrix.os != 'windows-latest' }}
         run: |
           python -m pip install dist/scenedetect-${{ env.scenedetect_version }}.tar.gz
           scenedetect version
@@ -101,7 +104,6 @@ jobs:
           python -m pip uninstall -y scenedetect
 
       - name: Smoke Test Package (Wheel)
-        if: ${{ matrix.os != 'windows-latest' }}
         run: |
           python -m pip install dist/scenedetect-${{ env.scenedetect_version }}-py3-none-any.whl
           scenedetect version
diff --git a/.github/workflows/check-code-format.yml b/.github/workflows/check-code-format.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python 3.11
         uses: actions/setup-python@v3
         with:
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -37,7 +37,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v2
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
@@ -15,6 +15,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@v3
diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml
@@ -20,10 +20,10 @@ jobs:
       scenedetect_docs_dest: ''
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: 'pip'
diff --git a/.github/workflows/generate-website.yml b/.github/workflows/generate-website.yml
@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
           cache: 'pip'
diff --git a/dist/package-info.rst b/dist/package-info.rst
@@ -5,13 +5,10 @@ PySceneDetect
 Video Scene Cut Detection and Analysis Tool
 ----------------------------------------------------------
 
-.. image:: https://img.shields.io/github/actions/workflow/status/Breakthrough/PySceneDetect/build.yml
-   :target: https://github.com/Breakthrough/PySceneDetect/actions
-
-.. image:: https://img.shields.io/github/release/Breakthrough/PySceneDetect.svg
+.. image:: https://img.shields.io/pypi/status/scenedetect.svg
    :target: https://github.com/Breakthrough/PySceneDetect
 
-.. image:: https://img.shields.io/pypi/status/scenedetect.svg
+.. image:: https://img.shields.io/github/release/Breakthrough/PySceneDetect.svg
    :target: https://github.com/Breakthrough/PySceneDetect
 
 .. image:: https://img.shields.io/pypi/l/scenedetect.svg
@@ -22,21 +19,19 @@ Video Scene Cut Detection and Analysis Tool
 
 ----------------------------------------------------------
 
-Website: https://www.scenedetect.com/
-
 Documentation: https://www.scenedetect.com/docs
 
 Github Repo: https://github.com/Breakthrough/PySceneDetect/
 
-----------------------------------------------------------
+Install: ``pip install --upgrade scenedetect[opencv]``
 
-PySceneDetect is a command-line tool and Python library which analyzes a video, looking for scene changes or cuts. PySceneDetect integrates with external tools (e.g. `ffmpeg`, `mkvmerge`) to automatically split the video into individual clips when using the `split-video` command and has several other features.
+----------------------------------------------------------
 
-Install: ``pip install --upgrade scenedetect[opencv]``
+**PySceneDetect** is a tool for detecting shot changes in videos, and can automatically split videos into separate clips.  PySceneDetect is free and open-source software, and has several detection methods to find fast-cuts and threshold-based fades.
 
-Split video via CLI: ``scenedetect -i video.mp4 split-video``
+For example, to split a video: ``scenedetect -i video.mp4 split-video``
 
-Split video using Python API:
+You can also use the Python API (`docs <https://www.scenedetect.com/docs/latest/>`_) to do the same:
 
 .. code-block:: python
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,13 +6,15 @@
 PySceneDetect Documentation
 #######################################################################
 
-This documentation covers the PySceneDetect command-line interface (the `scenedetect` command) and Python API (the `scenedetect` module).  The latest release of PySceneDetect can be installed via `pip install scenedetect[opencv]`. Windows builds and source releases can be found at `scenedetect.com/download <http://www.scenedetect.com/download/>`_. Note that PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
+Welcome to the PySceneDetect docs. The docs are split into two separate parts: one for the command-line interface (the `scenedetect` command) and another for the Python API (the `scenedetect` module).
+
+You can install the latest release of PySceneDetect by running `pip install scenedetect[opencv]` or downloading the Windows build from `scenedetect.com/download <http://www.scenedetect.com/download/>`_. PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
 
 .. note::
 
      If you see any errors in the documentation, or want to suggest improvements, feel free to raise an issue on `the PySceneDetect issue tracker <https://github.com/Breakthrough/PySceneDetect/issues>`_.
 
-The latest source code for PySceneDetect can be found on Github at `github.com/Breakthrough/PySceneDetect <http://github.com/Breakthrough/PySceneDetect>`_.
+PySceneDetect development happens on Github at `github.com/Breakthrough/PySceneDetect <http://github.com/Breakthrough/PySceneDetect>`_.
 
 
 ***********************************************************************
diff --git a/website/pages/api.md b/website/pages/api.md
@@ -75,5 +75,5 @@ Processing is done by calling the `process_frame(...)` function for all frames i
 
 `post_process(...)` is called **after** the final frame has been processed, to allow for any stored scene cuts to be written *if required* (e.g. in the case of the `ThresholdDetector`).
 
-You may also want to look into the implementation of current detectors to understand how frame metrics are saved/loaded to/from a [`StatsManager`](https://pyscenedetect.readthedocs.io/projects/Manual/en/stable/api/stats_manager.html) for caching and allowing values to be written to a stats file for users to graph and find trends in to tweak detector options.  Also see the documentation for the [`SceneManager`](https://pyscenedetect.readthedocs.io/projects/Manual/en/stable/api/scene_manager.html) for details.
+You may also want to look into the implementation of current detectors to understand how frame metrics are saved/loaded to/from a [`StatsManager`](https://www.scenedetect.com/docs/latest/api/stats_manager.html) for caching and allowing values to be written to a stats file for users to graph and find trends in to tweak detector options.  Also see the documentation for the [`SceneManager`](https://www.scenedetect.com/docs/latest/api/scene_manager.html) for details.
 
diff --git a/website/pages/cli.md b/website/pages/cli.md
@@ -1,7 +1,7 @@
 
 # PySceneDetect CLI
 
-See [the documentation](../docs/stable/) for a complete reference to the `scenedetect` command with more examples.
+See [the documentation](../docs/latest/) for a complete reference to the `scenedetect` command with more examples.
 
 ## Quickstart
 
diff --git a/website/pages/contributing.md b/website/pages/contributing.md
@@ -1,40 +1,48 @@
 
 ## <span class="fa fa-bug"></span>&nbsp; Bug Reports
 
-Bugs, issues, features, and improvements to PySceneDetect are handled through [the issue tracker on Github](https://github.com/Breakthrough/PySceneDetect/issues).  If you run into any bugs using PySceneDetect, please [create a new issue](https://github.com/Breakthrough/PySceneDetect/issues/new).  Provide as much detail as you can - include an example that clearly demonstrates the problem (if possible), and make sure to include any/all relevant program output or error messages.
+Bugs, issues, features, and improvements to PySceneDetect are handled through [the issue tracker on Github](https://github.com/Breakthrough/PySceneDetect/issues).  If you run into any bugs using PySceneDetect, please [create a new issue](https://github.com/Breakthrough/PySceneDetect/issues/new/choose).
 
-When submitting bug reports, please provide debug logs by adding `-l BUG_REPORT.txt` to your `scenedetect` command, and attach the generated `BUG_REPORT.txt` file.
-
-Before opening a new issue, please do [search for any existing issues](https://github.com/Breakthrough/PySceneDetect/issues?q=) (both open and closed) which might report similar issues/bugs to avoid creating duplicate entries.  If you do find a duplicate report, feel free to add any additional information you feel may be relevant.
+Try to [find an existing issue](https://github.com/Breakthrough/PySceneDetect/issues?q=) before creating a new one, as there may be a workaround posted there.  Additional information is also helpful for existing reports.
 
 ## <span class="fa fa-cogs"></span>&nbsp; Contributing to Development
 
-The development of PySceneDetect is done on the Github Repo, guided by [the feature roadmap](features.md).  Code you wish to submit should be attached to a dedicated entry in [the issue tracker](https://github.com/Breakthrough/PySceneDetect/issues?q=) (with the appropriate tags for bugfixes, new features, enhancements, etc...), and allows for easier communication regarding development structure.  Feel free to create a new entry if required, as some planned features or bugs/issues may not yet exist in the tracker.
+Development of PySceneDetect happens on [github.com/Breakthrough/PySceneDetect](https://github.com/Breakthrough/PySceneDetect).  Pull requests are accepted and encouraged.  Where possible, PRs should be submitted with a dedicated entry in [the issue tracker](https://github.com/Breakthrough/PySceneDetect/issues?q=).  Issues and features are typically grouped into version milestones.
+
+The following checklist covers the basics of pre-submission requirements:
 
-All submitted code should be linted with pylint, and follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) as closely as possible.  Also, ensure that you search through [all existing issues](https://github.com/Breakthrough/PySceneDetect/issues?q=) (both open and closed) beforehand to avoid creating duplicate entries.
+ - Code passes all unit tests (run `pytest`)
+ - Code is formatted (run `python -m yapf -i -r scenedetect/ tests/` to format in place)
+ - Generally follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
 
 Note that PySceneDetect is released under the BSD 3-Clause license, and submitted code should comply with this license (see [License & Copyright Information](copyright.md) for details).
 
 ## <span class="fa fa-cogs"></span>&nbsp; Features That Need Help
 
 The following is a "wishlist" of features which PySceneDetect eventually should have, but does not currently due to lack of resources.  Anyone who is able to contribute in any capacity to these items is encouraged to do so by starting a dialogue by opening a new issue on Github as per above.
 
-### GUI
-
-A graphical user interface will be crucial for making PySceneDetect approchable by a wider audience.  There have been several suggested designs, but nothing concrete has been developed yet.  Any proposed solution for the GUI should work across Windows, Linux, and OSX.
-
-### Localization
+### Flash Suppression
 
-PySceneDetect currently is not localized for other languages.  Anyone who can help improve how localization can be approached for development material is encouraged to contribute in any way possible.  Whether it is the GUI program, the command line interface, or documentation, localization will allow PySceneDetect to be used by much more users in their native languages.
+Some detection methods struggle with bright flashes and fast camera movement.  The detection pipeline has some filters in place to deal with these cases, but there are still drawbacks.  We are actively seeking methods which can improve both performance and accuracy in these cases.
 
-### Automatic Threshold / Peak Detection
+### Automatic Thresholding
 
 The `detect-content` command requires a manual threshold to be set currently.  Methods to use peak detection to dynamically determine when scene cuts occur would allow for the program to work with a much wider amount of material without requiring manual tuning, but would require statistical analysis.
 
 Ideally, this would be something like `-threshold=auto` as a default.
 
-### Advanced Detection Strategies
+### Dissolve Detection
+
+Depending on the length of the dissolve and parameters being used, detection accuracy for these types of cuts can vary widely.  A method to improve accuracy with minimal performance loss is an open problem.
 
-Research into advanced scene detection for content detection would be most useful, perhaps in terms of histogram analysis or edge detection.  This could be integrated into the existing `detect-content` command, or be a separate command.  The real blocker here is achieving reasonable performance utilizing the current software architecture.
+### Advanced Strategies
+
+Research into detection methods and performance are ongoing. All contributions in this regard are most welcome.
+
+### GUI
+
+A graphical user interface will be crucial for making PySceneDetect approchable by a wider audience.  There have been several suggested designs, but nothing concrete has been developed yet.  Any proposed solution for the GUI should work across Windows, Linux, and OSX.
+
+### Localization
 
-There are many open issues on the issue tracker that contain reference implementations contributed by various community members.  There are already several concepts which are proven to be viable candidates for production, but still require some degree optimization.
+PySceneDetect currently is not localized for other languages.  Anyone who can help improve how localization can be approached for development material is encouraged to contribute in any way possible.  Whether it is the GUI program, the command line interface, or documentation, localization will allow PySceneDetect to be used by much more users in their native languages.
diff --git a/website/pages/index.md b/website/pages/index.md
@@ -3,13 +3,12 @@
 
 <div class="important">
 <h3 class="wy-text-neutral"><span class="fa fa-info-circle wy-text-info"></span>&nbsp; Latest Release: <b>v0.6.3</b> (March 9, 2024)</h3>
-<a href="download/" class="btn btn-success" style="margin-bottom:8px;" role="button"><span class="fa fa-download"></span>&nbsp; <b>Download</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="changelog/" class="btn btn-info" style="margin-bottom:8px;" role="button"><span class="fa fa-reorder"></span>&nbsp; <b>Changelog</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="docs/" class="btn btn-warning" style="margin-bottom:8px;" role="button"><span class="fa fa-gear"></span>&nbsp; <b>Documentation</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="cli/" class="btn btn-danger" style="margin-bottom:8px;" role="button"><span class="fa fa-book"></span>&nbsp; <b>Getting Started</b></a>
+<a href="download/" class="btn btn-success" style="margin-bottom:8px;" role="button"><span class="fa fa-download"></span>&nbsp; <b>Download</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="changelog/" class="btn btn-info" style="margin-bottom:8px;" role="button"><span class="fa fa-reorder"></span>&nbsp; <b>Changelog</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="docs/latest/" class="btn btn-warning" style="margin-bottom:8px;" role="button"><span class="fa fa-gear"></span>&nbsp; <b>Documentation</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="cli/" class="btn btn-danger" style="margin-bottom:8px;" role="button"><span class="fa fa-book"></span>&nbsp; <b>Getting Started</b></a>
 <br/>
 See the changelog for the latest release notes and known issues.
 </div>
 
-**PySceneDetect** is a tool/library for **detecting shot changes in videos** ([example](cli.md)), and **automatically splitting the video into separate clips**.  PySceneDetect is free and open-source software, and there are [several detection methods available](features.md) - from simple threshold-based fade in/out detection, to advanced content aware fast-cut detection of each shot.
-
+**PySceneDetect** is a tool for **detecting shot changes in videos** ([example](cli.md)), and can **automatically split the video into separate clips**.  PySceneDetect is free and open-source software, and has several [detection methods](features.md#detection-methods) to find fast-cuts and threshold-based fades.
 
 <h3>Quickstart</h3>
 
diff --git a/website/pages/literature.md b/website/pages/literature.md
@@ -3,6 +3,8 @@
 
 PySceneDetect is a useful tool for statistical analysis of video.  Below are links to various research articles/papers which have either used PySceneDetect as a part of their analysis, or propose more accurate detection algorithms using the current implementation as a comparison.
 
+ - [Panda-70M: Captioning 70M Videos with Multiple Cross-Modality Teachers](https://arxiv.org/abs/2402.19479) by Tsai-Shien Chen, Aliaksandr Siarohin, Willi Menapace, Ekaterina Deyneka, Hsiang-wei Chao, Byung Eun Jeon, Yuwei Fang, Hsin-Ying Lee, Jian Ren, Ming-Hsuan Yang, Sergey Tulyakov (2024)
+
  - [Stable Remaster: Bridging the Gap Between Old Content and New Displays](https://arxiv.org/pdf/2306.06803.pdf) by Nathan Paull, Shuvam Keshari, Yian Wong (2023)
 
  - [LoL-V2T: Large-Scale Esports Video Description Dataset](https://ieeexplore.ieee.org/abstract/document/9522986) by Tsunehiko Tanaka, Edgar Simo-Serra (2021)

Original file line number	Diff line number	Diff line change
@@ -75,5 +75,5 @@ Processing is done by calling the `process_frame(...)` function for all frames i
`75`	`75`
`76`	`76`	`post_process(...)` is called after the final frame has been processed, to allow for any stored scene cuts to be written if required (e.g. in the case of the `ThresholdDetector`).
`77`	`77`
`78`		-You may also want to look into the implementation of current detectors to understand how frame metrics are saved/loaded to/from a [`StatsManager`](https://pyscenedetect.readthedocs.io/projects/Manual/en/stable/api/stats_manager.html) for caching and allowing values to be written to a stats file for users to graph and find trends in to tweak detector options. Also see the documentation for the [`SceneManager`](https://pyscenedetect.readthedocs.io/projects/Manual/en/stable/api/scene_manager.html) for details.
	`78`	+You may also want to look into the implementation of current detectors to understand how frame metrics are saved/loaded to/from a [`StatsManager`](https://www.scenedetect.com/docs/latest/api/stats_manager.html) for caching and allowing values to be written to a stats file for users to graph and find trends in to tweak detector options. Also see the documentation for the [`SceneManager`](https://www.scenedetect.com/docs/latest/api/scene_manager.html) for details.
`79`	`79`