[dist] Update Windows dependencies for 0.7 release

Breakthrough · Breakthrough · commit 5d5bcac81367 · 2026-04-28T23:15:22.000-04:00
diff --git a/.github/workflows/build-windows.yml b/.github/workflows/build-windows.yml
@@ -36,8 +36,7 @@ jobs:
         python-version: ["3.13"]
 
     env:
-      ffmpeg-version: "7.1"
-      IMAGEIO_FFMPEG_EXE: ""
+      ffmpeg-version: "8.1"
 
     steps:
       - uses: actions/checkout@v5
@@ -70,7 +69,11 @@ jobs:
         shell: bash
         run: |
           7z e ffmpeg-${{ env.ffmpeg-version }}-full_build.7z ffmpeg.exe -r
-          echo "IMAGEIO_FFMPEG_EXE=`realpath ffmpeg.exe`" >> "$GITHUB_ENV"
+          export PATH="$(pwd):$PATH"
+          # moviepy.config resolves ffmpeg via imageio_ffmpeg at import time; `--no-binary`
+          # strips the bundled binary, so point at the GyanD ffmpeg we just extracted
+          # for both pytest and the subsequent pyinstaller step.
+          echo "IMAGEIO_FFMPEG_EXE=$(realpath ffmpeg.exe)" >> "$GITHUB_ENV"
           python -m pytest -vv
 
       - name: Build PySceneDetect
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -60,7 +60,7 @@ jobs:
                 core.setFailed(`Workflow "${workflowName}" did not succeed for tag ${tag}. Conclusion was "${workflowConclusions[workflowName].conclusion}". See: ${workflowConclusions[workflowName].html_url}`);
                 allSuccess = false;
               } else {
-                console.log(`✅ Workflow "${workflowName}" succeeded for tag ${tag}.`);
+                console.log(`[OK] Workflow "${workflowName}" succeeded for tag ${tag}.`);
               }
             }
 
diff --git a/RELEASE-PLAN.md b/RELEASE-PLAN.md
@@ -33,14 +33,14 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 
 - [ ] Unit tests green locally and in CI: `pytest -vv` (should collect `-m 'not release'` by default).
 - [ ] `ruff check scenedetect/ tests/` and `ruff format --check scenedetect/ tests/` pass.
-- [ ] Release test suite green: tag a disposable `vX.Y.Z-release-rc` or use `workflow_dispatch` on `.github/workflows/release-test.yml` - all 4 jobs (`static`, `release-tests`, `install-matrix`, `long-stress`) green across the 3-OS × 2-Python matrix. See `RELEASE-TEST-PLAN.md` for what the suite covers.
+- [ ] Release test suite green: tag a disposable `vX.Y.Z-release-rc` or use `workflow_dispatch` on `.github/workflows/release-test.yml` - all 4 jobs (`static`, `release-tests`, `install-matrix`, `long-stress`) green across the 3-OS x 2-Python matrix. See `RELEASE-TEST-PLAN.md` for what the suite covers.
 - [ ] `resources` branch has the artifacts the release tests need (goldens under `tests/resources/goldens/`, `tests/resources/stress_15min.mp4`). Re-push if any golden was regenerated.
 - [ ] Manual smoke: fresh venv, `pip install .` (pulls opencv-python automatically) then `pip install .[pyav]`; run `scenedetect -i <video> detect-content list-scenes save-images` and eyeball the output. Repeat after `python packaging/build_headless.py && pip install .` to verify the headless variant.
 - [ ] `pip-audit` clean (or exceptions documented in the changelog).
 
 ## 5. Windows installer
 
-- [ ] `python scripts/pre_release.py --release` passes (enforces `.aip` ↔ `__version__` parity, writes `packaging/windows/.version_info`).
+- [ ] `python scripts/pre_release.py --release` passes (enforces `.aip` <-> `__version__` parity, writes `packaging/windows/.version_info`).
 - [ ] `pyinstaller packaging/windows/scenedetect.spec` produces a working `scenedetect.exe` - run it against a sample video.
 - [ ] `python scripts/stage_windows_dist.py --ffmpeg-dir <dir> --portable-zip` populates `dist/scenedetect/` with ffmpeg, third-party licenses, sphinx docs, and emits the portable `.zip`. Pass `--ffmpeg-dir` pointing at a recent extracted [GyanD codexffmpeg](https://github.com/GyanD/codexffmpeg/releases) build; omit it only for offline builds (uses the bundled `packaging/windows/thirdparty.7z` with a stub `LICENSE-FFMPEG`).
 - [ ] `python scripts/bump_installer.py --sync-files` and commit the .aip diff (refreshes the APPDIR baseline so CI's per-build `--sync-only` diff stays small).
@@ -49,7 +49,7 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 
 > **GUI required for structural changes.** `scripts/bump_installer.py` covers routine version bumps and `--sync-files` covers dependency-driven file-list changes, but anything that touches the *project structure* of the .aip still needs the AdvancedInstaller GUI. Examples:
 >
-> - Moving the .aip or its source tree (the build's `SourcePath` references are stored relative to the .aip and aren't rewritten by `/NewSync` - cf. the `dist/installer/` → `packaging/windows/installer/` move that broke the relative paths until they were edited in the GUI).
+> - Moving the .aip or its source tree (the build's `SourcePath` references are stored relative to the .aip and aren't rewritten by `/NewSync` - cf. the `dist/installer/` -> `packaging/windows/installer/` move that broke the relative paths until they were edited in the GUI).
 > - Adding/removing build configurations, features, or prerequisites.
 > - Editing dialog layouts, branding bitmaps, install sequences, custom actions, file associations, or shortcuts.
 > - Changing `UpgradeCode`, install directory layout (`APPDIR` location), or per-component attributes.
diff --git a/appveyor.yml b/appveyor.yml
@@ -20,7 +20,7 @@ environment:
     secure: QRCPoNYF1nqgXDn7pHgBzg==
   ai_license_salt:
     secure: +Gy+SRk8JUsaM+5pMEKITiJxdLilrxHpkKlrZzR3C9DPwdgYLGxt5sJn6uXuAJg7e6JsKHcT7tRks/HcSKkHPw==
-  ffmpeg_version: "8.0"
+  ffmpeg_version: "8.1"
 
 # SignPath Config for Code Signing
 deploy:
@@ -42,6 +42,10 @@ install:
   - python -m pip install --upgrade -r packaging/windows/requirements.txt --no-binary imageio-ffmpeg
   - appveyor DownloadFile https://github.com/GyanD/codexffmpeg/releases/download/%ffmpeg_version%/ffmpeg-%ffmpeg_version%-full_build.7z
   - 7z e ffmpeg-%ffmpeg_version%-full_build.7z -odist/ffmpeg ffmpeg.exe LICENSE -r
+  # moviepy.config reads FFMPEG_BINARY (which routes through imageio_ffmpeg) at import time.
+  # `--no-binary imageio-ffmpeg` strips the bundled ffmpeg, so point it at the GyanD copy
+  # we just extracted; otherwise pre_release.py and pyinstaller analysis crash on
+  # `import scenedetect`. The runtime hook (pyi_rth_scenedetect.py) does the same at exe runtime.
   - 'SET IMAGEIO_FFMPEG_EXE=%APPVEYOR_BUILD_FOLDER%\\dist\\ffmpeg\\ffmpeg.exe'
 
   - echo * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
diff --git a/packaging/windows/pyi_rth_scenedetect.py b/packaging/windows/pyi_rth_scenedetect.py
@@ -0,0 +1,28 @@
+#
+#         PySceneDetect: Python-Based Video Scene Detector
+#   ---------------------------------------------------------------
+#     [  Site: http://www.bcastell.com/projects/PySceneDetect/   ]
+#     [  Github: https://github.com/Breakthrough/PySceneDetect/  ]
+#     [  Documentation: http://www.scenedetect.com/docs/         ]
+#
+# Copyright (C) 2026 Brandon Castellano <http://www.bcastell.com>.
+#
+# Runtime hook: redirect imageio_ffmpeg and moviepy to the bundled ffmpeg.exe (staged next to
+# scenedetect.exe) so we ship a single copy of ffmpeg. Runs before any user imports, which is
+# required because moviepy.config reads FFMPEG_BINARY at import time.
+
+
+def _pyi_rthook():
+    import os
+    import sys
+
+    bundle_dir = os.path.dirname(sys.executable)
+    ffmpeg_exe = os.path.join(bundle_dir, "ffmpeg.exe")
+    if os.path.isfile(ffmpeg_exe):
+        os.environ["IMAGEIO_FFMPEG_EXE"] = ffmpeg_exe
+        os.environ.setdefault("FFMPEG_BINARY", ffmpeg_exe)
+        os.environ["PATH"] = bundle_dir + os.pathsep + os.environ.get("PATH", "")
+
+
+_pyi_rthook()
+del _pyi_rthook
diff --git a/packaging/windows/requirements.txt b/packaging/windows/requirements.txt
@@ -1,12 +1,12 @@
 # PySceneDetect Requirements for Windows Build
-av==14.2.0
-click==8.1.8
-opencv-python-headless==4.11.0.86
+av==17.0.1
+click==8.2.1
 imageio-ffmpeg==0.6.0
-moviepy==2.1.2
-numpy==2.2.3
-platformdirs==4.3.6
-tqdm==4.67.1
+moviepy==2.2.1
+opencv-python-headless==4.13.0.92
+numpy==2.4.4
+platformdirs==4.9.6
+tqdm==4.67.3
 
 # Build-only and test-only requirements.
 pyinstaller
diff --git a/packaging/windows/scenedetect.spec b/packaging/windows/scenedetect.spec
@@ -1,7 +1,19 @@
 # -*- mode: python -*-
 
+import os
+
+from PyInstaller.utils.hooks import copy_metadata
+
 block_cipher = None
 
+# moviepy/imageio resolve their own version via importlib.metadata at import time,
+# which needs the dist-info dirs bundled alongside the modules.
+_metadata = (
+    copy_metadata('moviepy')
+    + copy_metadata('imageio')
+    + copy_metadata('imageio_ffmpeg')
+)
+
 
 a = Analysis(['../../scenedetect/__main__.py'],
              pathex=['.'],
@@ -11,15 +23,30 @@ a = Analysis(['../../scenedetect/__main__.py'],
                 ('README.txt', '.'),
                 ('../../LICENSE', '.'),
                 ('../../scenedetect.cfg', '.')
-            ],
-             hiddenimports=[],
+            ] + _metadata,
+             hiddenimports=['moviepy', 'imageio', 'imageio_ffmpeg'],
              hookspath=[],
-             runtime_hooks=[],
+             runtime_hooks=['packaging/windows/pyi_rth_scenedetect.py'],
              excludes=[],
              win_no_prefer_redirects=False,
              win_private_assemblies=False,
              cipher=block_cipher)
 
+# Drop imageio_ffmpeg's bundled ffmpeg-*.exe so we don't ship two copies of
+# ffmpeg. The runtime hook (pyi_rth_scenedetect.py) redirects imageio_ffmpeg
+# and moviepy at the GyanD ffmpeg.exe staged next to scenedetect.exe by
+# scripts/stage_windows_dist.py. Keep __init__.py — pyinstaller-hooks-contrib
+# declares `imageio_ffmpeg.binaries` as a hidden import, so the package still
+# has to be importable.
+def _drop_bundled_ffmpeg(toc):
+    # TOC dest paths use the OS-native separator, so normalize before matching.
+    prefix = 'imageio_ffmpeg' + os.sep + 'binaries' + os.sep
+    return [t for t in toc if not (
+        t[0].startswith(prefix) and not t[0].endswith('__init__.py')
+    )]
+a.binaries = _drop_bundled_ffmpeg(a.binaries)
+a.datas = _drop_bundled_ffmpeg(a.datas)
+
 pyz = PYZ(a.pure, a.zipped_data,
              cipher=block_cipher)
 exe = EXE(pyz,
diff --git a/tests/release/synthetic.py b/tests/release/synthetic.py
@@ -20,7 +20,7 @@
 def generate_vfr_swing(output_path: str):
     """Generates a VFR video with three segments separated by visible luma steps.
 
-    Segments: black @ 1 fps (5s) → gray @ 60 fps (5s) → white @ 1 fps (5s).
+    Segments: black @ 1 fps (5s) -> gray @ 60 fps (5s) -> white @ 1 fps (5s).
     Solid colors make the cuts unambiguous for ContentDetector; mixed rates
     exercise the VFR code path. Boundary timestamps: 5.0s and 10.0s.
     """
diff --git a/tests/release/test_backends.py b/tests/release/test_backends.py
@@ -79,7 +79,7 @@ def test_cross_backend_consistency(rel_path, is_vfr):
         )
         if is_vfr:
             for a, e in zip(actual, expected, strict=True):
-                # Tolerance: ~one frame at 30 fps. Plan calls for ±1 local-frame-duration;
+                # Tolerance: ~one frame at 30 fps. Plan calls for +/-1 local-frame-duration;
                 # 50 ms is a conservative superset that still catches real drift.
                 assert abs(a - e) < 0.05, (
                     f"VFR timestamp drift between {backend} and {reference}: {a} vs {e}"
diff --git a/tests/release/test_long_video.py b/tests/release/test_long_video.py
@@ -70,7 +70,7 @@ def monitor_memory():
         stop_event.set()
         monitor_thread.join()
 
-    # Assert peak RSS ≤ 3x baseline
+    # Assert peak RSS <= 3x baseline
     # Some increase is expected due to internal buffering, but not 3x for 480p.
     assert peak_rss[0] <= 3 * baseline_rss, (
         f"Memory leak suspected: Peak RSS {peak_rss[0]} > 3x Baseline RSS {baseline_rss}"
diff --git a/tests/release/test_validation.py b/tests/release/test_validation.py
@@ -109,10 +109,10 @@ def test_output_otio_rational_time_precision(test_video_file, tmp_path):
     video_track = timeline.tracks[0]
     assert len(list(video_track)) == len(scene_list)
 
-    # `value` is a frame count derived from seconds * fps, serialized at 10µs
+    # `value` is a frame count derived from seconds * fps, serialized at 10us
     # precision (round(..., 6)) per 914ca31. Guards the `90.00000000000001` class
     # of float-cast drift by asserting the rounded value never carries spurious
-    # sub-10µs noise.
+    # sub-10us noise.
     for clip in video_track:
         for rt in (clip.source_range.start_time, clip.source_range.duration):
             assert abs(rt.value - round(rt.value, 6)) == 0, (
diff --git a/tests/test_detectors.py b/tests/test_detectors.py
@@ -31,7 +31,7 @@
     ThresholdDetector,
 )
 
-# Untyped so each entry retains its concrete `type[…]` for parameterized construction
+# Untyped so each entry retains its concrete `type[...]` for parameterized construction
 # (calls below pass detector-specific kwargs like `min_scene_len`).
 FAST_CUT_DETECTORS = (
     AdaptiveDetector,
diff --git a/tests/test_output.py b/tests/test_output.py
@@ -366,7 +366,7 @@ def test_write_scene_list_fcpx(tmp_path: Path):
 
     fmt = root.find("resources/format")
     assert fmt is not None
-    # 24000/1001 fps → frameDuration is the reciprocal: 1001/24000s.
+    # 24000/1001 fps -> frameDuration is the reciprocal: 1001/24000s.
     assert fmt.attrib["frameDuration"] == "1001/24000s"
     assert fmt.attrib["width"] == "1280"
     assert fmt.attrib["height"] == "544"
@@ -494,7 +494,7 @@ def test_write_scene_list_otio_no_audio(tmp_path: Path):
 
 
 def test_write_scene_list_otio_rational_time_precision(tmp_path: Path):
-    """Serialized frame-count values must be free of sub-10µs float drift (cf. 914ca31)."""
+    """Serialized frame-count values must be free of sub-10us float drift (cf. 914ca31)."""
     # Frames on integer-frame boundaries under NTSC 24000/1001: seconds * 23.976...
     # should land on integers but floats can produce values like 214.00001 without
     # the explicit round(..., 6) in the writer.
@@ -514,4 +514,4 @@ def test_write_scene_list_otio_rational_time_precision(tmp_path: Path):
         for clip in track["children"]:
             for key in ("start_time", "duration"):
                 value = clip["source_range"][key]["value"]
-                assert value == round(value, 6), f"value {value!r} carries sub-10µs float drift"
+                assert value == round(value, 6), f"value {value!r} carries sub-10us float drift"
diff --git a/tests/test_vfr.py b/tests/test_vfr.py
@@ -37,7 +37,7 @@
 
 # Expected scene cuts for `goldeneye-vfr-drop3.mp4` - a synthetic VFR clip created from the first
 # 10s of goldeneye.mp4 by dropping every 3rd frame (frames 2,5,8,...). PTS durations alternate
-# between 1001 and 2002 (time_base=1/24000), nominal fps=24000/1001, avg fps≈16. The last scene
+# between 1001 and 2002 (time_base=1/24000), nominal fps=24000/1001, avg fps ~= 16. The last scene
 # ends at the clip boundary and may vary slightly between backends.
 EXPECTED_SCENES_VFR_DROP3: list[tuple[str, str]] = [
     ("00:00:00.000", "00:00:03.754"),
diff --git a/website/pages/changelog.md b/website/pages/changelog.md
@@ -742,3 +742,17 @@ Care was taken to minimize changes for most common API uses, however more advanc
  * Remove `advance` parameter from `VideoStream.read()`
  * Remove `SceneDetector.stats_manager_required` property, no longer required
  * `SceneDetector` is now a [Python abstract class](https://docs.python.org/3/library/abc.html)
+
+### Windows Distribution
+
+ - [general] Updates to Windows distributions:
+    - av 14.2.0 -> 17.0.1
+    - click 8.1.8 -> 8.2.1
+    - imageio-ffmpeg 0.6.0
+    - moviepy 2.1.2 -> 2.2.1
+    - numpy 2.2.3 -> 2.4.4
+    - opencv-python-headless 4.11.0.86 -> 4.13.0.92
+    - platformdirs 4.3.6 -> 4.9.6
+    - tqdm 4.67.1 -> 4.67.3
+    - ffmpeg 8.0 -> 8.1
+ - [general] Reduce size of Windows distribution by requiring `imageio_ffmpeg` to use non-bundled instance
diff --git a/website/pages/download.md b/website/pages/download.md
@@ -15,7 +15,7 @@ PySceneDetect requires at least Python 3.10 or higher.
 <h3 class="wy-text-neutral"><tt>pip install --upgrade scenedetect-headless</tt></h3>
 </div>
 
-PySceneDetect is available via `pip` as either [`scenedetect`](https://pypi.org/project/scenedetect/) (depends on `opencv-python`) or [`scenedetect-headless`](https://pypi.org/project/scenedetect-headless/) (depends on `opencv-python-headless`). Both ship the same `scenedetect` Python module — install whichever OpenCV variant suits your environment.
+PySceneDetect is available via `pip` as either [`scenedetect`](https://pypi.org/project/scenedetect/) (depends on `opencv-python`) or [`scenedetect-headless`](https://pypi.org/project/scenedetect-headless/) (depends on `opencv-python-headless`). Both ship the same `scenedetect` Python module -- install whichever OpenCV variant suits your environment.
 
 ## Windows Build (64-bit Only) &nbsp; <span class="wy-text-neutral"><span class="fa fa-windows"></span></span>
 
diff --git a/website/pages/faq.md b/website/pages/faq.md
@@ -16,7 +16,7 @@ For server environments without GUI libraries, install the headless variant inst
 pip install scenedetect-headless
 ```
 
-Both packages ship the same `scenedetect` Python module — you only need one.
+Both packages ship the same `scenedetect` Python module -- you only need one.
 
 #### How can I enable video splitting support?
 

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ jobs:`
`60`	`60`	core.setFailed(`Workflow "${workflowName}" did not succeed for tag ${tag}. Conclusion was "${workflowConclusions[workflowName].conclusion}". See: ${workflowConclusions[workflowName].html_url}`);
`61`	`61`	`allSuccess = false;`
`62`	`62`	`} else {`
`63`		- console.log(`✅ Workflow "${workflowName}" succeeded for tag ${tag}.`);
	`63`	+ console.log(`[OK] Workflow "${workflowName}" succeeded for tag ${tag}.`);
`64`	`64`	`}`
`65`	`65`	`}`
`66`	`66`
Original file line number	Diff line number	Diff line change
`@@ -79,7 +79,7 @@ def test_cross_backend_consistency(rel_path, is_vfr):`
`79`	`79`	`)`
`80`	`80`	`if is_vfr:`
`81`	`81`	`for a, e in zip(actual, expected, strict=True):`
`82`		`- # Tolerance: ~one frame at 30 fps. Plan calls for ±1 local-frame-duration;`
	`82`	`+ # Tolerance: ~one frame at 30 fps. Plan calls for +/-1 local-frame-duration;`
`83`	`83`	`# 50 ms is a conservative superset that still catches real drift.`
`84`	`84`	`assert abs(a - e) < 0.05, (`
`85`	`85`	`f"VFR timestamp drift between {backend} and {reference}: {a} vs {e}"`