[build] Cache installer & ffmpeg on signed builder

Author: Breakthrough

RELEASE-PLAN.md

@@ -11,7 +11,7 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 ## 1. Code & version
 
 - [ ] Bump `__version__` in `scenedetect/__init__.py`.
-- [ ] Bump the installer project: `python scripts/bump_installer.py` (rewrites `ProductVersion`, regenerates `ProductCode`, updates the MSI filename via the AdvancedInstaller CLI). Add `--sync-files` after `pyinstaller` if any bundled dependency versions changed since the last release - this re-syncs APPDIR from `dist/scenedetect/` and replaces the manual "delete install dir + re-add files" GUI step. `scripts/pre_release.py --release` asserts the resulting `ProductVersion` matches `__version__`.
+- [ ] Bump the installer project: `python scripts/update_installer.py` (rewrites `ProductVersion`, regenerates `ProductCode`, updates the MSI filename via the AdvancedInstaller CLI). Add `--sync-files` after `pyinstaller` if any bundled dependency versions changed since the last release - this re-syncs APPDIR from `dist/scenedetect/` and replaces the manual "delete install dir + re-add files" GUI step. `scripts/pre_release.py --release` asserts the resulting `ProductVersion` matches `__version__`.
 - [ ] No `-dev` / pre-release suffix on the version string for a final release.
 
 > **Note:** `pyproject.toml` does not declare a `version` field - the single source of truth is `scenedetect/__init__.py`; the Windows installer `.aip` is the only other place to keep in sync.
@@ -42,19 +42,19 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 
 - [ ] `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).
+- [ ] `python scripts/stage_windows_dist.py --ffmpeg-dir <dir>` 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/update_installer.py --sync-files` and commit the .aip diff (refreshes the APPDIR baseline so CI's per-build `--sync-only` diff stays small).
 - [ ] Build the MSI via Advanced Installer (`packaging/windows/installer/PySceneDetect.aip`); install into a clean Windows VM and run the CLI.
 - [ ] After both `pyinstaller` and the MSI build are done (and the portable `.zip` is staged at `dist/PySceneDetect-X.Y.Z-portable.zip`), run `python scripts/generate_manifest.py` to produce `dist/PySceneDetect-X.Y.Z.manifest.json` (per-file SHA256 audit of every artifact) and `dist/SHA256SUMS` (flat `sha256sum -c` compatible). Both are attached to the GitHub release in step 7.
 
-> **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:
+> **GUI required for structural changes.** `scripts/update_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).
 > - 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.
 >
-> When in doubt, open the .aip in AdvancedInstaller, make the change, save, and commit the resulting diff. Re-run `bump_installer.py` afterwards if the version-identity fields need refreshing.
+> When in doubt, open the .aip in AdvancedInstaller, make the change, save, and commit the resulting diff. Re-run `update_installer.py` afterwards if the version-identity fields need refreshing.
 
 ## 6. Cut the release
 

appveyor.yml

@@ -2,6 +2,11 @@
 
 build: false
 
+cache:
+  - 'ffmpeg-%ffmpeg_version%-full_build.7z -> appveyor.yml'
+  - 'packaging\windows\installer\advinst.msi -> appveyor.yml'
+  - '%LOCALAPPDATA%\uv\cache -> pyproject.toml'
+
 # Branches applies to tags as well. We only build on tagged releases of the form vX.Y.Z-release
 branches:
   only:
@@ -37,10 +42,10 @@ install:
   - echo * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
   - 'SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%'
   - python --version
-  - python -m pip install --upgrade pip build wheel virtualenv setuptools
-  - python -m pip install .[docs]
-  - 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
+  - python -m pip install uv
+  - uv pip install --system .[docs]
+  - uv pip install --system -r packaging/windows/requirements.txt --no-binary imageio-ffmpeg
+  - if not exist ffmpeg-%ffmpeg_version%-full_build.7z 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
@@ -57,7 +62,7 @@ install:
   # portable .zip - keeps CI and local builds in sync (see scripts/stage_windows_dist.py).
   - python scripts/pre_release.py --release
   - pyinstaller packaging/windows/scenedetect.spec
-  - python scripts/stage_windows_dist.py --ffmpeg-dir dist/ffmpeg --portable-zip
+  - python scripts/stage_windows_dist.py --ffmpeg-dir dist/ffmpeg
 
   - echo * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
   - echo * *                         BUILDING MSI INSTALLER                          * *
@@ -66,7 +71,7 @@ install:
   - cd packaging/windows/installer
   - ps: iex ((New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/appveyor/secure-file/master/install.ps1'))
   - appveyor-tools\secure-file -decrypt license65.dat.enc -secret %ai_license_secret% -salt %ai_license_salt%
-  - appveyor DownloadFile https://www.advancedinstaller.com/downloads/advinst.msi
+  - if not exist advinst.msi appveyor DownloadFile https://www.advancedinstaller.com/downloads/advinst.msi
   - msiexec /i advinst.msi /qn
   # Resolve the installed Advanced Installer bin path dynamically - the upstream
   # MSI is unversioned so the directory name (Advanced Installer X.Y.Z) drifts.
@@ -82,7 +87,7 @@ install:
   # release tag and must stay stable across rebuilds for upgrade-chain integrity.
   # On non-tag builds, also pass --dev so the MSI is named PySceneDetect-{ver}-dev-win64.msi
   # (keeps dev artifacts distinguishable from signed releases).
-  - if "%APPVEYOR_REPO_TAG%"=="true" (python scripts/bump_installer.py --sync-only) else (python scripts/bump_installer.py --sync-only --dev)
+  - if "%APPVEYOR_REPO_TAG%"=="true" (python scripts/update_installer.py --sync-only) else (python scripts/update_installer.py --sync-only --dev)
   # Snapshot the post-sync .aip and the actual payload tree as build artifacts.
   # The committed .aip is a baseline; CI adapts it to its own pyinstaller output
   # and we never write back to git, so these snapshots are the authoritative

scripts/generate_assets.py

@@ -1,8 +1,15 @@
-#!/usr/bin/env python
-"""Generate pyscenedetect.ico and logo PNGs from SVG sources.
-
-Requires Inkscape (for SVG rasterization) and Pillow (for ICO generation).
-"""
+#
+#            PySceneDetect: Python-Based Video Scene Detector
+#   -------------------------------------------------------------------
+#     [  Site:    https://scenedetect.com                           ]
+#     [  Docs:    https://scenedetect.com/docs/                     ]
+#     [  Github:  https://github.com/Breakthrough/PySceneDetect/    ]
+#
+# Copyright (C) 2026 Brandon Castellano <http://www.bcastell.com>.
+# PySceneDetect is licensed under the BSD 3-Clause License; see the
+# included LICENSE file, or visit one of the above pages for details.
+#
+"""Generate pyscenedetect.ico and logo PNGs from SVG sources. Requires Inkscape and Pillow."""
 
 import contextlib
 import shutil

scripts/generate_goldens.py

@@ -9,10 +9,7 @@
 # PySceneDetect is licensed under the BSD 3-Clause License; see the
 # included LICENSE file, or visit one of the above pages for details.
 #
-"""Golden Cut-List Generator
-
-This script generates golden cut-lists in JSON format for the release test suite.
-"""
+"""Generates golden cut-lists in JSON format for the release test suite."""
 
 import argparse
 import json

scripts/generate_manifest.py

@@ -38,7 +38,7 @@
 
 
 def msi_version(raw: str) -> str:
-    # Mirror scripts/bump_installer.py - the artifact filename uses the
+    # Mirror scripts/update_installer.py - the artifact filename uses the
     # normalized X.Y.Z form, not the Python __version__ string.
     parts = [re.split(r"[^\d]", p, maxsplit=1)[0] for p in raw.split(".")]
     while len(parts) < 3:

scripts/pre_release.py

@@ -10,11 +10,13 @@
 # included LICENSE file, or visit one of the above pages for details.
 #
 
-# Pre-release script to run before invoking `pyinstaller`:
-#
-#     python scripts/pre_release.py
-#     pyinstaller packaging/windows/scenedetect.spec
-#
+"""
+Pre-release script to run before invoking `pyinstaller` when building the Windows distribution:
+```bash
+python scripts/pre_release.py
+pyinstaller packaging/windows/scenedetect.spec
+```
+"""
 import sys
 from pathlib import Path
 
@@ -23,7 +25,7 @@
 sys.path.insert(0, str(REPO_DIR))
 sys.path.insert(0, str(SCRIPTS_DIR))
 
-from bump_installer import msi_version  # noqa: E402
+from update_installer import msi_version  # noqa: E402
 
 import scenedetect  # noqa: E402
 
@@ -40,12 +42,12 @@
     installer_aip = INSTALLER_AIP.read_text()
     # The .aip stores the numeric MSI form (e.g. "0.7.0"), not the Python __version__
     # (which may be "0.7-dev0", "0.7", "0.7.1", ...). Normalize through the same
-    # function bump_installer.py uses to write the .aip so the comparison is apples-to-apples.
+    # function update_installer.py uses to write the .aip so the comparison is apples-to-apples.
     expected = msi_version(VERSION)
     aip_row = f'<ROW Property="ProductVersion" Value="{expected}" Options="32"/>'
     assert aip_row in installer_aip, (
         f"Installer ProductVersion does not match normalized {VERSION!r} ({expected!r}). "
-        f"Run `python scripts/bump_installer.py` to refresh the .aip."
+        f"Run `python scripts/update_installer.py` to refresh the .aip."
     )
 
 with VERSION_INFO.open("wb") as f:

scripts/stage_windows_dist.py

@@ -9,35 +9,36 @@
 # PySceneDetect is licensed under the BSD 3-Clause License; see the
 # included LICENSE file, or visit one of the above pages for details.
 #
-"""Stage non-pyinstaller assets into dist/scenedetect/.
+"""Stages Windows distribution assets into dist/scenedetect/.
 
-Pyinstaller produces only scenedetect.exe + _internal/. This script adds
-the rest of what both the AdvancedInstaller MSI and the portable ZIP need:
-ffmpeg.exe + its LICENSE, the project LICENSE / README.txt, third-party
-licenses, and sphinx-built docs. Mirrors the inline staging steps that
-appveyor.yml used to do, so CI and local builds stay in sync.
-
-Sequence in a release:
+Sequence in a release to generate the installer:
 
+```bash
     python scripts/pre_release.py
     pyinstaller packaging/windows/scenedetect.spec
-    python scripts/stage_windows_dist.py --ffmpeg-dir <dir> --portable-zip
-    python scripts/bump_installer.py --sync-files
+    python scripts/stage_windows_dist.py --ffmpeg-dir <dir>
+    python scripts/update_installer.py --sync-files
     AdvancedInstaller.com /build packaging/windows/installer/PySceneDetect.aip
     python scripts/generate_manifest.py
+```
 
---ffmpeg-dir points at a directory containing ffmpeg.exe and its LICENSE
-(e.g. the extracted GyanD codexffmpeg release). If omitted, the script
-falls back to extracting ffmpeg.exe from packaging/windows/thirdparty.7z;
-LICENSE-FFMPEG is then a stub since the bundled archive doesn't carry it.
+This script assumes it is run on a Windows machine.
 """
 
+# TODO: This should be called from the Github Actions workflow as well, right now it's only
+# done from the appveyor one. When that's done it should be merged with update_installer.py
+# into a combined "prepare_windows_dist.py".
+
 import argparse
 import re
 import shutil
 import subprocess
 import sys
 import zipfile
+
+if sys.platform != "win32":
+    print("Error: stage_windows_dist.py must be run on Windows.", file=sys.stderr)
+    sys.exit(1)
 from pathlib import Path
 
 REPO_DIR = Path(__file__).resolve().parent.parent
@@ -174,11 +175,6 @@ def main() -> None:
         help="Directory containing ffmpeg.exe and its LICENSE. "
         "If omitted, ffmpeg is extracted from packaging/windows/thirdparty.7z.",
     )
-    parser.add_argument(
-        "--portable-zip",
-        action="store_true",
-        help="Also produce dist/PySceneDetect-<version>-portable.zip.",
-    )
     args = parser.parse_args()
 
     if not DIST_TREE.exists():
@@ -191,9 +187,7 @@ def main() -> None:
     copy_file(PACKAGING_WIN / "README.txt", DIST_TREE / "README.txt")
     stage_thirdparty_licenses()
     build_docs()
-
-    if args.portable_zip:
-        make_portable_zip(msi_version(scenedetect.__version__))
+    make_portable_zip(msi_version(scenedetect.__version__))
 
 
 if __name__ == "__main__":

scripts/bump_installer.py scripts/update_installer.pyscripts/bump_installer.py renamed to scripts/update_installer.py

@@ -9,21 +9,14 @@
 # PySceneDetect is licensed under the BSD 3-Clause License; see the
 # included LICENSE file, or visit one of the above pages for details.
 #
-"""Bump the AdvancedInstaller .aip project for a release.
+"""Update the AdvancedInstaller .aip project for a release.
 
 Usage:
-    python scripts/bump_installer.py                    # version bump only
-    python scripts/bump_installer.py --sync-files       # bump + re-sync APPDIR
-    python scripts/bump_installer.py --sync-only        # re-sync APPDIR only (CI)
-    python scripts/bump_installer.py --sync-only --dev  # CI dev build (renames MSI)
-    python scripts/bump_installer.py --version 0.7.0    # explicit version override
-
-The committed .aip is a baseline; CI's --sync-only adapts it per build and is
-never written back to git. Refresh locally with --sync-files before each release.
-
-All paths shell out to AdvancedInstaller.com to preserve .aip invariants
-(line endings, attribute ordering, GUID casing). Override CLI discovery with
-the ADVINST environment variable.
+    python scripts/update_installer.py                    # version bump only
+    python scripts/update_installer.py --sync-files       # bump + re-sync APPDIR
+    python scripts/update_installer.py --sync-only        # re-sync APPDIR only (CI)
+    python scripts/update_installer.py --sync-only --dev  # CI dev build (renames MSI)
+    python scripts/update_installer.py --version 0.7.0    # explicit version override
 """
 
 import argparse