Merge branch 'develop' into histogram-luma-detector

.github/actions/setup-ffmpeg/action.yml

@@ -0,0 +1,41 @@
+name: 'Setup FFmpeg'
+inputs:
+  github-token:
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup FFmpeg (latest)
+      id: latest
+      continue-on-error: true
+      uses: FedericoCarboni/setup-ffmpeg@v3
+      with:
+        github-token: ${{ inputs.github-token }}
+
+    - name: Setup FFmpeg (7.0.0)
+      if: ${{ steps.latest.outcome == 'failure' }}
+      id: v7-0-0
+      continue-on-error: true
+      uses: FedericoCarboni/setup-ffmpeg@v3
+      with:
+        github-token: ${{ inputs.github-token }}
+        ffmpeg-version: "7.0.0"
+
+    - name: Setup FFmpeg (6.1.1)
+      if: ${{ steps.v7-0-0.outcome == 'failure' }}
+      id: v6-1-1
+      continue-on-error: true
+      uses: FedericoCarboni/setup-ffmpeg@v3
+      with:
+        github-token: ${{ inputs.github-token }}
+        ffmpeg-version: "6.1.1"
+
+  # The oldest version we allow falling back to must not have `continue-on-error: true`
+    - name: Setup FFmpeg (6.1.0)
+      if: ${{ steps.v6-1-1.outcome == 'failure' }}
+      id: v6-1-0
+      uses: FedericoCarboni/setup-ffmpeg@v3
+      with:
+        github-token: ${{ inputs.github-token }}
+        ffmpeg-version: "6.1.0"

.github/workflows/build-windows.yml

@@ -30,11 +30,14 @@ jobs:
       matrix:
         python-version: ["3.9"]
 
+    env:
+      ffmpeg-version: "7.0"
+
     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'
@@ -50,16 +53,16 @@ jobs:
           git fetch --depth=1 https://github.com/Breakthrough/PySceneDetect.git refs/heads/resources:refs/remotes/origin/resources
           git checkout refs/remotes/origin/resources -- tests/resources/
 
-      - name: Download FFMPEG
+      - name: Download FFMPEG ${{ env.ffmpeg-version }}
         uses: dsaltares/[email protected]
         with:
           repo: 'GyanD/codexffmpeg'
-          version: 'tags/6.0'
-          file: 'ffmpeg-6.0-full_build.7z'
+          version: 'tags/${{ env.ffmpeg-version }}'
+          file: 'ffmpeg-${{ env.ffmpeg-version }}-full_build.7z'
 
       - name: Unit Test
         run: |
-          7z e ffmpeg-6.0-full_build.7z ffmpeg.exe -r
+          7z e ffmpeg-${{ env.ffmpeg-version }}-full_build.7z ffmpeg.exe -r
           python -m pytest -vv
 
       - name: Build PySceneDetect
@@ -77,7 +80,7 @@ jobs:
           Move-Item -Path dist/windows/README* -Destination dist/scenedetect/
           Move-Item -Path dist/windows/LICENSE* -Destination dist/scenedetect/thirdparty/
           Move-Item -Path scenedetect/_thirdparty/LICENSE* -Destination dist/scenedetect/thirdparty/
-          7z e -odist/ffmpeg ffmpeg-6.0-full_build.7z LICENSE -r
+          7z e -odist/ffmpeg ffmpeg-${{ env.ffmpeg-version }}-full_build.7z LICENSE -r
           Move-Item -Path ffmpeg.exe -Destination dist/scenedetect/ffmpeg.exe
           Move-Item -Path dist/ffmpeg/LICENSE -Destination dist/scenedetect/thirdparty/LICENSE-FFMPEG
 
@@ -95,7 +98,7 @@ jobs:
     runs-on: windows-latest
     needs: build
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: resources
 

.github/workflows/build.yml

@@ -27,22 +27,39 @@ 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"]
+        os: [macos-13, macos-14, ubuntu-20.04, ubuntu-latest, windows-latest]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        exclude:
+          # macos-14 builders use M1 (ARM64) which does not have a Python 3.7 package available.
+          - os: macos-14
+            python-version: "3.7"
+
+    env:
+      # Version is extracted below and used to find correct package install path.
+      scenedetect_version: ""
+      # Setuptools must be pinned for the Python 3.7 builders.
+      setuptools_version: "${{ matrix.python-version == '3.7' && '==62.3.4' || '' }}"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Setup FFmpeg
+        # TODO: This action currently does not work for non-x64 builders (e.g. macos-14):
+        # https://github.com/federicocarboni/setup-ffmpeg/issues/21
+        if: ${{ runner.arch == 'X64' }}
+        uses: ./.github/actions/setup-ffmpeg
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - 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.
         run: |
-          python -m pip install --upgrade pip build wheel virtualenv setuptools==62.3.4
+          python -m pip install --upgrade pip build wheel virtualenv setuptools${{ env.setuptools_version }}
           pip install av opencv-python-headless --only-binary :all:
           pip install -r requirements_headless.txt
 
@@ -51,21 +68,6 @@ jobs:
           git fetch --depth=1 https://github.com/Breakthrough/PySceneDetect.git refs/heads/resources:refs/remotes/origin/resources
           git checkout refs/remotes/origin/resources -- tests/resources/
 
-      # TODO: Cache this: https://github.com/actions/cache
-      # TODO: Install ffmpeg/mkvtoolnix on all runners.
-      - name: Download FFMPEG
-        if: ${{ matrix.os == 'windows-latest' }}
-        uses: dsaltares/[email protected]
-        with:
-          repo: 'GyanD/codexffmpeg'
-          version: 'tags/6.0'
-          file: 'ffmpeg-6.0-full_build.7z'
-
-      - name: Extract FFMPEG
-        if: ${{ matrix.os == 'windows-latest' }}
-        run: |
-          7z e ffmpeg-6.0-full_build.7z ffmpeg.exe -r
-
       - name: Unit Tests
         run: |
           python -m pytest -vv
@@ -77,22 +79,13 @@ jobs:
           python -m scenedetect -i tests/resources/testvideo.mp4 -b pyav time --end 2s
           python -m pip uninstall -y scenedetect
 
-      - name: Build Documentation
-        if: ${{ matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest' }}
-        run: |
-          pip install -r docs/requirements.txt
-          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 +94,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
@@ -110,7 +102,7 @@ jobs:
           python -m pip uninstall -y scenedetect
 
       - name: Upload Package
-        if: ${{ matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest' }}
+        if: ${{ matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' }}
         uses: actions/upload-artifact@v3
         with:
           name: scenedetect-dist

.github/workflows/check-code-format.yml

@@ -17,11 +17,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.11
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
         uses: actions/setup-python@v3
         with:
-          python-version: '3.11'
+          python-version: '3.12'
           cache: 'pip'
 
       - name: Update pip

.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

.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

.github/workflows/generate-docs.yml

@@ -20,12 +20,12 @@ jobs:
       scenedetect_docs_dest: ''
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
           cache: 'pip'
 
       - name: Set Destination (Releases)

.github/workflows/generate-website.yml

@@ -14,12 +14,12 @@ 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
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
           cache: 'pip'
 
       - name: Install Dependencies

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
 

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>`_.
 
 
 ***********************************************************************

scenedetect.cfg

@@ -39,13 +39,14 @@
 # Method to use for downscaling (nearest, linear, cubic, area, lanczos4).
 #downscale-method = linear
 
-# Minimum length of a given scene (shorter scenes will be merged).
+# Minimum length of a given scene.
 #min-scene-len = 0.6s
 
-# Merge last scene if it is shorter than min-scene-len (yes/no)
+# Merge last scene if it is shorter than min-scene-len (yes/no). This can occur
+# when a cut is detected just before the video ends.
 #merge-last-scene = no
 
-# Drop scenes shorter than min-scene-len instead of merging (yes/no)
+# Drop scenes shorter than min-scene-len instead of merging (yes/no).
 #drop-short-scenes = no
 
 # Verbosity of console output (debug, info, warning, error, or none).
@@ -64,6 +65,14 @@
 # Sensitivity threshold from 0 to 255. Lower values are more sensitive.
 #threshold = 27
 
+# Minimum length of a given scene (overrides [global] option).
+#min-scene-len = 0.6s
+
+# Mode to use when filtering scenes to comply with min-scene-len:
+#   merge: Consecutive scenes shorter than min-scene-len are combined.
+#   suppress: No new scenes can be generated until min-scene-len passes.
+#filter-mode = merge
+
 # Weight to place on each component when calculating frame score (the value
 # `threshold` is compared against). The components are in the order
 # (delta_hue, delta_sat, delta_lum, delta_edges). Description of components:
@@ -83,8 +92,10 @@
 # than or equal to 3. If None, automatically set using video resolution.
 #kernel-size = -1
 
-# Minimum length of a given scene (overrides [global] option).
-#min-scene-len = 0.6s
+# Mode to use for enforcing min-scene-len:
+#   merge: Consecutive scenes shorter than min-scene-len are combined.
+#   suppress: No new scenes can be generated until min-scene-len passes.
+#filter-mode = merge
 
 
 [detect-threshold]

scenedetect/__init__.py

@@ -36,7 +36,7 @@
 from scenedetect.video_stream import VideoStream, VideoOpenFailure
 from scenedetect.video_splitter import split_video_ffmpeg, split_video_mkvmerge
 from scenedetect.scene_detector import SceneDetector
-from scenedetect.detectors import ContentDetector, AdaptiveDetector, ThresholdDetector, HistogramDetector
+from scenedetect.detectors import ContentDetector, AdaptiveDetector, ThresholdDetector, HistogramDetector, HashDetector
 from scenedetect.backends import (AVAILABLE_BACKENDS, VideoStreamCv2, VideoStreamAv,
                                   VideoStreamMoviePy, VideoCaptureAdapter)
 from scenedetect.stats_manager import StatsManager, StatsFileCorrupt
@@ -47,7 +47,7 @@
 
 # Used for module identification and when printing version & about info
 # (e.g. calling `scenedetect version` or `scenedetect about`).
-__version__ = '0.6.3'
+__version__ = '0.7-dev0'
 
 init_logger()
 logger = getLogger('pyscenedetect')