[dist] Split package into regular vs. headless variant

Author: Breakthrough

.github/workflows/build.yml

@@ -97,6 +97,21 @@ jobs:
           scenedetect -i tests/resources/testvideo.mp4 -b pyav time --end 2s
           python -m pip uninstall -y scenedetect
 
+      - name: Build Package (Headless)
+        shell: bash
+        run: |
+          python packaging/build_headless.py
+          python -m build
+          git checkout pyproject.toml
+
+      - name: Smoke Test Package (Headless Wheel)
+        run: |
+          python -m pip install dist/scenedetect_headless-${{ env.scenedetect_version }}-py3-none-any.whl
+          scenedetect version
+          scenedetect -i tests/resources/testvideo.mp4 -b opencv time --end 2s
+          scenedetect -i tests/resources/testvideo.mp4 -b pyav time --end 2s
+          python -m pip uninstall -y scenedetect-headless
+
       - name: Upload Package
         if: ${{ matrix.python-version == '3.13' && matrix.os == 'ubuntu-latest' }}
         uses: actions/upload-artifact@v6

.github/workflows/publish-pypi.yml

@@ -99,6 +99,8 @@ jobs:
 
       - name: Build Package
         run: |
+          python -m build
+          python packaging/build_headless.py
           python -m build
           mkdir pkg
           mv dist/*.tar.gz pkg/

.github/workflows/release-test.yml

@@ -41,6 +41,9 @@ jobs:
       - name: Build and Check
         run: |
           python -m build
+          python packaging/build_headless.py
+          python -m build
+          git checkout pyproject.toml
           twine check dist/*
       - name: pip-audit
         # CVE-2026-3219 in pip 26.0.1 has no fix version available upstream

RELEASE-PLAN.md

@@ -35,7 +35,7 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 - [ ] `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.
 - [ ] `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 .` then `pip install .[opencv]` then `pip install .[pyav]`; run `scenedetect -i <video> detect-content list-scenes save-images` and eyeball the output.
+- [ ] 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
@@ -53,8 +53,8 @@ Version referenced below as `X.Y[.Z]` - replace with the real version throughout
 
 ## 7. Publish
 
-- [ ] `publish-pypi.yml` ran on the tag and uploaded successfully. Verify at https://pypi.org/project/scenedetect/.
-- [ ] Smoke-test PyPI: in a fresh venv, `pip install scenedetect==X.Y.Z` (bare), then with `[opencv]` and `[pyav]`. CLI launches.
+- [ ] `publish-pypi.yml` ran on the tag and uploaded successfully. Verify both projects: https://pypi.org/project/scenedetect/ and https://pypi.org/project/scenedetect-headless/.
+- [ ] Smoke-test PyPI: in a fresh venv, `pip install scenedetect==X.Y.Z`; CLI launches and `pip show scenedetect` lists `opencv-python`. Repeat in a second venv with `pip install scenedetect-headless==X.Y.Z`; verify it lists `opencv-python-headless`.
 - [ ] Create GitHub Release from the `vX.Y[.Z]` tag, body = changelog section, attach Windows installer MSI + portable `.zip`.
 - [ ] Deploy website: `generate-website.yml` picks up the changelog / download page updates.
 - [ ] Deploy docs: `generate-docs.yml` publishes the new version.

packaging/build_headless.py

@@ -0,0 +1,29 @@
+#
+#         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) 2014 Brandon Castellano <http://www.bcastell.com>.
+#
+
+# Generates the headless variant by mutating pyproject.toml in place.
+# Run this before `python -m build` to produce scenedetect-headless artifacts.
+# Modifies pyproject.toml in place; revert via `git checkout pyproject.toml`.
+
+from pathlib import Path
+
+PYPROJECT = Path(__file__).resolve().parent.parent / "pyproject.toml"
+
+content = PYPROJECT.read_text()
+
+assert 'name = "scenedetect"' in content
+content = content.replace('name = "scenedetect"', 'name = "scenedetect-headless"', 1)
+
+assert '"opencv-python",' in content
+content = content.replace('"opencv-python",', '"opencv-python-headless",', 1)
+
+PYPROJECT.write_text(content)
+
+print("Generated headless pyproject.toml.")