[docs] Remove scenedetect-core references

Breakthrough · Breakthrough · commit a1ca4bc9fee1 · 2026-07-22T22:26:00.000-04:00
scenedetect-core 0.7.1 has been yanked from PyPI and the package discontinued: pip cannot safely support multiple packages installing the same module files, and restructuring the published packages around a shared core would break in-place upgrades. See #558. Update install docs to cover only scenedetect/scenedetect-headless and note the discontinuation in the changelog.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -88,7 +88,7 @@ jobs:
       - name: Build Package
         shell: bash
         run: |
-          # Builds scenedetect-core plus the scenedetect/scenedetect-headless variants.
+          # Builds the scenedetect/scenedetect-headless packages.
           python packaging/build_all.py
           echo "scenedetect_version=`python -c \"import scenedetect; print(scenedetect.__version__.replace('-', '.'))\"`" >> "$GITHUB_ENV"
 
@@ -132,40 +132,16 @@ jobs:
           scenedetect -i tests/resources/testvideo.mp4 -b opencv time --end 2s
           scenedetect -i tests/resources/testvideo.mp4 -b pyav time --end 2s
 
-      - name: Smoke Test Package (Core Only)
-        shell: bash
-        run: |
-          python -m venv .smoke-core
-          VENV_BIN=.smoke-core/bin
-          [ -d .smoke-core/Scripts ] && VENV_BIN=.smoke-core/Scripts
-          source "$VENV_BIN/activate"
-          pip install "dist/scenedetect_core-${{ env.scenedetect_version }}-py3-none-any.whl"
-          # Core declares no OpenCV variant; importing without one must raise the friendly error.
-          python -c "
-          try:
-              import scenedetect
-              raise AssertionError('import should fail without cv2')
-          except ModuleNotFoundError as ex:
-              assert ex.name == 'cv2', ex
-          "
-          # Any variant satisfies the library; core must not drag in CLI deps or the entry point.
-          pip install opencv-python-headless
-          python -c "import scenedetect; print(scenedetect.__version__)"
-          python -c "import importlib.util as u; assert u.find_spec('click') is None, 'click must not be a core dependency'"
-          python -c "import importlib.util as u; assert u.find_spec('tqdm') is None, 'tqdm must not be a core dependency'"
-          if command -v scenedetect >/dev/null 2>&1; then
-            echo "The scenedetect entry point must not be installed by scenedetect-core"
-            exit 1
-          fi
-
       - name: Smoke Test Package (Upgrade From 0.7)
         shell: bash
         run: |
-          # All three packages ship the code (no metapackage layering) precisely so that
-          # in-place upgrades from pre-0.7.1 installs keep working - a code-carrying dist
+          # Both packages ship the code (no metapackage layering) precisely so that
+          # in-place upgrades from older installs keep working - a code-carrying dist
           # flipped to a code-free metapackage would break here, since uninstalling the old
-          # version deletes module files a dependency just wrote. Keep this as a regression
-          # guard for that failure mode (https://scenedetect.com/issues/558).
+          # version deletes module files a dependency just wrote. This is also why the
+          # short-lived scenedetect-core (published in 0.7.1 only) was yanked rather than
+          # layered on. Keep this as a regression guard for that failure mode
+          # (https://scenedetect.com/issues/558).
           python -m venv .smoke-upgrade
           VENV_BIN=.smoke-upgrade/bin
           [ -d .smoke-upgrade/Scripts ] && VENV_BIN=.smoke-upgrade/Scripts
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -103,8 +103,8 @@ jobs:
           run-id: ${{ steps.resolve.outputs.run-id }}
 
       - name: List artifact contents
-        # Expect 6 files: sdist + wheel for each of scenedetect-core, scenedetect,
-        # and scenedetect-headless. All three projects publish from this one step;
+        # Expect 4 files: sdist + wheel for each of scenedetect and
+        # scenedetect-headless. Both projects publish from this one step;
         # each needs a trusted publisher configured on PyPI/TestPyPI for this workflow.
         run: ls -la pkg/
 
diff --git a/.github/workflows/release-test.yml b/.github/workflows/release-test.yml
@@ -48,7 +48,7 @@ jobs:
           fi
       - name: Build and Check
         run: |
-          # Builds scenedetect-core plus the scenedetect/scenedetect-headless variants.
+          # Builds the scenedetect/scenedetect-headless packages.
           python packaging/build_all.py
           # Glob by extension: dist/ also holds tracked website assets (dist/logo/),
           # which `twine check dist/*` would reject as an unknown distribution.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -213,6 +213,5 @@ jobs:
             echo "Release $TAG verified and published:"
             echo "  https://pypi.org/project/scenedetect/$VERSION/"
             echo "  https://pypi.org/project/scenedetect-headless/$VERSION/"
-            echo "  https://pypi.org/project/scenedetect-core/$VERSION/"
             echo "  https://github.com/$GH_REPO/pkgs/container/pyscenedetect"
           fi
diff --git a/RELEASE-PLAN.md b/RELEASE-PLAN.md
@@ -54,7 +54,7 @@ Optional: version referenced below as `X.Y[.Z]` - replace with the real version
 ## 6. Publish & Release Checks
 
 - [ ] Dispatch `release.yml` (Release Orchestrator) with the release tag while the Github release is still a **draft**. It runs the verify-then-publish ladder (MSI install/upgrade test -> TestPyPI -> publish Github release -> PyPI -> Docker), verifying each stage before the next; `verify-only` stops before anything goes public. See the header of `release.yml` for details.
-- [ ] Verify all three projects: https://pypi.org/project/scenedetect/, https://pypi.org/project/scenedetect-headless/, and https://pypi.org/project/scenedetect-core/.
+- [ ] Verify both projects: https://pypi.org/project/scenedetect/ and https://pypi.org/project/scenedetect-headless/.
 - [ ] Deploy website: `generate-website.yml`
 - [ ] Deploy docs: `generate-docs.yml`
 - [ ] Merge release branch back into `main`, verify `docs/LATEST_VERSION` is correct
diff --git a/docs/api.rst b/docs/api.rst
@@ -58,7 +58,7 @@ Most types/functions are also available directly from the `scenedetect` package
 
     .. code:: python
 
-        scenedetect<0.8
+        scenedetect~=0.7
 
 
 .. _scenedetect-quickstart:
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -312,13 +312,13 @@ Options
 
   Max distance between hash values (0.0 to 1.0) of adjacent frames. Lower values are more sensitive to changes.
 
-  Default: ``0.395``
+  Default: ``0.35``
 
 .. option:: -s SIZE, --size SIZE
 
   Size of square of low frequency data to include from the discrete cosine transform.
 
-  Default: ``16``
+  Default: ``8``
 
 .. option:: -l FRAC, --lowpass FRAC
 
@@ -363,13 +363,13 @@ Options
 
   Max difference (0.0 to 1.0) between histograms of adjacent frames. Lower values are more sensitive to changes.
 
-  Default: ``0.05``
+  Default: ``0.2``
 
 .. option:: -b NUM, --bins NUM
 
   The number of bins to use for the histogram calculation.
 
-  Default: ``256``
+  Default: ``128``
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,7 @@ PySceneDetect Documentation
 
 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` (or `pip install scenedetect-headless` on servers without GUI libraries), or by downloading the Windows build from `scenedetect.com/download <http://www.scenedetect.com/download/>`_. Library-only installs that need a specific OpenCV variant (e.g. `opencv-contrib-python`) can use `pip install scenedetect-core`, which has no CLI dependencies and lets you supply any OpenCV package. PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
+You can install the latest release of PySceneDetect by running `pip install scenedetect` (or `pip install scenedetect-headless` on servers without GUI libraries), or by downloading the Windows build from `scenedetect.com/download <http://www.scenedetect.com/download/>`_. PySceneDetect requires `ffmpeg` or `mkvmerge` for video splitting support.
 
 .. note::
 
diff --git a/packaging/build_all.py b/packaging/build_all.py
@@ -7,20 +7,23 @@
 #
 # Copyright (C) 2026 Brandon Castellano <http://www.bcastell.com>.
 #
-"""Builds all three PySceneDetect distributions into dist/:
+"""Builds the two published PySceneDetect distributions into dist/:
 
-  - scenedetect-core: minimal dependencies (numpy only, no OpenCV variant declared,
-    no console script) - built from the repo root pyproject.toml
-  - scenedetect / scenedetect-headless: the same code plus an OpenCV variant, the
-    CLI dependencies, and the `scenedetect` console script
+  - scenedetect / scenedetect-headless: the full package (code, an OpenCV variant,
+    the CLI dependencies, and the `scenedetect` console script), produced by
+    temporarily swapping packaging/variants/pyproject-<name>.toml into the repo
+    root (restored afterwards, even on failure)
 
-All three are code-carrying packages built from the repo root, so they share the
-same source, readme, and dynamic version. The scenedetect / scenedetect-headless
-variants are produced by temporarily swapping packaging/variants/pyproject-<name>.toml
-into the repo root (restored afterwards, even on failure).
+Both are standalone code-carrying packages built from the repo root, so they share
+the same source, readme, and dynamic version. The root pyproject.toml
+(`scenedetect-core`) is a development/local-install configuration only and is NOT
+built or published here: scenedetect-core 0.7.1 was briefly published and then
+yanked - layering packages over a shared core dist is unsafe with pip (co-installed
+variants double-own files, and converting an existing code-carrying name to a
+metapackage breaks in-place upgrades; see https://scenedetect.com/issues/558).
 
 Requires `build` (pip install build). Fails if dist/ ends up with any wheel/sdist
-besides the six expected artifacts, so clear stale build artifacts from dist/ first.
+besides the four expected artifacts, so clear stale build artifacts from dist/ first.
 (Other dist/ contents are ignored - e.g. dist/logo/ is tracked website assets.)
 """
 
@@ -63,7 +66,6 @@ def main() -> None:
             "and re-run."
         )
 
-    build()  # scenedetect-core from the unmodified repo root.
     try:
         for name in VARIANTS:
             variant = (ROOT / "packaging" / "variants" / f"pyproject-{name}.toml").read_text(
@@ -76,7 +78,7 @@ def main() -> None:
         PYPROJECT.write_text(original, encoding="utf-8")
 
     expected = set()
-    for name in ("scenedetect-core", *VARIANTS):
+    for name in VARIANTS:
         normalized = name.replace("-", "_")
         expected.add(f"{normalized}-{version}.tar.gz")
         expected.add(f"{normalized}-{version}-py3-none-any.whl")
diff --git a/packaging/package-info.rst b/packaging/package-info.rst
@@ -25,7 +25,7 @@ Github Repo: https://github.com/Breakthrough/PySceneDetect/
 
 Install: ``pip install --upgrade scenedetect`` (or ``scenedetect-headless`` for servers)
 
-Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``), `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``), and `scenedetect-core <https://pypi.org/project/scenedetect-core/>`_ (library only, minimal dependencies, bring your own OpenCV variant). All provide the same ``scenedetect`` module -- install only one.
+Packages: `scenedetect <https://pypi.org/project/scenedetect/>`_ (CLI + ``opencv-python``) and `scenedetect-headless <https://pypi.org/project/scenedetect-headless/>`_ (CLI + ``opencv-python-headless``). Both provide the same ``scenedetect`` module -- install only one.
 
 ----------------------------------------------------------
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -41,10 +41,13 @@ classifiers = [
     "Topic :: Utilities",
 ]
 # OpenCV is required at runtime but intentionally NOT declared: any of the four
-# opencv-python* variants satisfies the library, and downstream projects must be
-# able to pick their own (https://scenedetect.com/issues/558). The `scenedetect`
-# and `scenedetect-headless` packages (packaging/variants/) ship the same code
-# with a concrete OpenCV variant plus the CLI dependencies.
+# opencv-python* variants satisfies the library for development installs. This root
+# config (`scenedetect-core`) is used for local/dev installs only and is NOT
+# published to PyPI (0.7.1 was published briefly and yanked - layering the published
+# packages over a shared core dist is unsafe with pip; see
+# https://scenedetect.com/issues/558). The published `scenedetect` and
+# `scenedetect-headless` packages (packaging/variants/) ship the same code with a
+# concrete OpenCV variant plus the CLI dependencies.
 dependencies = [
     "numpy",
 ]
diff --git a/scenedetect.cfg b/scenedetect.cfg
@@ -126,7 +126,7 @@
 [detect-hash]
 # Threshold between 0.0 and 1.0 to set the relative difference between
 # hashes required to trigger a shot change. Lower values are more sensitive.
-#threshold = 0.395
+#threshold = 0.35
 
 # The ratio between 1 and 256 of how much low frequency information to keep.
 # Represents highest frequency which will pass the filter. 1 means keep all,
@@ -135,7 +135,7 @@
 
 # Size between 1 and 256 representing size of square of low frequency data to
 # use for the direct cosine transform (DCT).
-#size = 16
+#size = 8
 
 # Minimum length of a given scene (overrides [global] option).
 #min-scene-len = 0.6s
@@ -145,10 +145,10 @@
 # Threshold between 0.0 to 1.0 to set the relative difference between Y
 # channel histograms (YUV) required to trigger a shot change. Lower values
 # are more sensitive.
-#threshold = 0.05
+#threshold = 0.20
 
 # Number of bins between 1 and 256 to use for the histogram.
-#bins = 256
+#bins = 128
 
 # Minimum length of a given scene (overrides [global] option).
 #min-scene-len = 0.6s
diff --git a/scenedetect/_cli/config.py b/scenedetect/_cli/config.py
@@ -379,13 +379,13 @@ class FcpFormat(Enum):
     "detect-hash": {
         "min-scene-len": TimecodeValue(0),
         "lowpass": RangeValue(2, min_val=1, max_val=256),
-        "size": RangeValue(16, min_val=1, max_val=256),
-        "threshold": RangeValue(0.395, min_val=0.0, max_val=1.0),
+        "size": RangeValue(8, min_val=1, max_val=256),
+        "threshold": RangeValue(0.35, min_val=0.0, max_val=1.0),
     },
     "detect-hist": {
         "min-scene-len": TimecodeValue(0),
-        "threshold": RangeValue(0.05, min_val=0.0, max_val=1.0),
-        "bins": RangeValue(256, min_val=1, max_val=256),
+        "threshold": RangeValue(0.20, min_val=0.0, max_val=1.0),
+        "bins": RangeValue(128, min_val=1, max_val=256),
     },
     "detect-threshold": {
         "add-last-scene": True,
diff --git a/scenedetect/detectors/hash_detector.py b/scenedetect/detectors/hash_detector.py
@@ -46,8 +46,8 @@ class HashDetector(SceneDetector):
 
     def __init__(
         self,
-        threshold: float = 0.395,
-        size: int = 16,
+        threshold: float = 0.35,
+        size: int = 8,
         lowpass: int = 2,
         min_scene_len: TimecodeLike = 15,
     ):
diff --git a/scenedetect/detectors/histogram_detector.py b/scenedetect/detectors/histogram_detector.py
@@ -32,8 +32,8 @@ class HistogramDetector(SceneDetector):
 
     def __init__(
         self,
-        threshold: float = 0.05,
-        bins: int = 256,
+        threshold: float = 0.20,
+        bins: int = 128,
         min_scene_len: TimecodeLike = 15,
     ):
         """
diff --git a/scenedetect/platform.py b/scenedetect/platform.py
@@ -369,11 +369,12 @@ def get_system_version_info() -> str:
     # installed. Kept intentionally: the fallback is what recovers the version in the
     # frozen Windows build (which ships cv2 without any `.dist-info`), and the
     # `opencv-python` row is metadata-only, so it remains accurate on its own.
-    # The same code ships in three distributions: `scenedetect-core` (minimal deps)
-    # and the `scenedetect`/`scenedetect-headless` variants (OpenCV variant + CLI
-    # deps). Metadata-only lookups (no module fallback) so each row reflects which
-    # distribution is actually installed - e.g. frozen builds show "Not Installed"
-    # here rather than misattributing the module version.
+    # The same code ships in the `scenedetect`/`scenedetect-headless` distributions
+    # (OpenCV variant + CLI deps). `scenedetect-core` was published in 0.7.1 only and
+    # then yanked (see https://scenedetect.com/issues/558); its row is kept so lingering
+    # installs remain visible. Metadata-only lookups (no module fallback) so each row
+    # reflects which distribution is actually installed - e.g. frozen builds show
+    # "Not Installed" here rather than misattributing the module version.
     scenedetect_packages = (
         ("scenedetect-core", None),
         ("scenedetect-headless", None),
diff --git a/tests/test_detectors.py b/tests/test_detectors.py
@@ -97,15 +97,20 @@ def detect(self):
 def get_fast_cut_test_cases():
     """Fixture for parameterized test cases that detect fast cuts."""
     test_cases = []
-    # goldeneye.mp4 with min_scene_len = 15 (default)
+    # goldeneye.mp4 with min_scene_len = 15 (default). HistogramDetector's recalibrated defaults
+    # (threshold=0.20, bins=128) are less sensitive and do not trigger on the cut at frame 1260.
     test_cases += [
         pytest.param(
             TestCase(
                 path=get_absolute_path("resources/goldeneye.mp4"),
                 detector=detector_type(min_scene_len=15),
                 start_time=1199,
                 end_time=1450,
-                scene_boundaries=[1199, 1226, 1260, 1281, 1334, 1365],
+                scene_boundaries=(
+                    [1199, 1226, 1281, 1334, 1365]
+                    if detector_type is HistogramDetector
+                    else [1199, 1226, 1260, 1281, 1334, 1365]
+                ),
             ),
             id=f"{detector_type.__name__}/default",
         )
@@ -119,7 +124,11 @@ def get_fast_cut_test_cases():
                 detector=detector_type(min_scene_len=30),
                 start_time=1199,
                 end_time=1450,
-                scene_boundaries=[1199, 1260, 1334, 1365],
+                scene_boundaries=(
+                    [1199, 1281, 1334, 1365]
+                    if detector_type is HistogramDetector
+                    else [1199, 1260, 1334, 1365]
+                ),
             ),
             id=f"{detector_type.__name__}/m=30",
         )
@@ -241,7 +250,13 @@ def test_min_scene_len_accepts_time_values(detector_type, min_scene_len):
         detector=detector_type(min_scene_len=min_scene_len),
         start_time=1199,
         end_time=1450,
-        scene_boundaries=[1199, 1260, 1334, 1365],
+        # HistogramDetector's recalibrated defaults do not trigger on the cut at frame 1260
+        # (see `get_fast_cut_test_cases`).
+        scene_boundaries=(
+            [1199, 1281, 1334, 1365]
+            if detector_type is HistogramDetector
+            else [1199, 1260, 1334, 1365]
+        ),
     )
     scene_list = test_case.detect()
     start_frames = [timecode.frame_num for timecode, _ in scene_list]
diff --git a/website/pages/changelog.md b/website/pages/changelog.md
diff --git a/website/pages/download.md b/website/pages/download.md
diff --git a/website/pages/faq.md b/website/pages/faq.md
