[cli] Add SCENEDETECT_DEBUG mode and fix incorrect version detection

Caught during release smoke testing.

Author: Breakthrough

scenedetect/__main__.py

@@ -17,7 +17,7 @@
 from scenedetect._cli import scenedetect
 from scenedetect._cli.context import CliContext
 from scenedetect._cli.controller import run_scenedetect
-from scenedetect.platform import FakeTqdmLoggingRedirect, logging_redirect_tqdm
+from scenedetect.platform import DEBUG_MODE, FakeTqdmLoggingRedirect, logging_redirect_tqdm
 
 
 def main():
@@ -46,14 +46,14 @@ def main():
             run_scenedetect(context)
         except KeyboardInterrupt:
             logger.info("Stopped.")
-            if __debug__:
+            if DEBUG_MODE:
                 raise
+            raise SystemExit(1) from None
         except BaseException as ex:
-            if __debug__:
+            if DEBUG_MODE:
                 raise
-            else:
-                logger.critical("ERROR: Unhandled exception:", exc_info=ex)
-                raise SystemExit(1) from None
+            logger.critical("ERROR: Unhandled exception:", exc_info=ex)
+            raise SystemExit(1) from ex
 
 
 if __name__ == "__main__":

scenedetect/_cli/config.py

@@ -30,6 +30,7 @@
 from scenedetect.detector import FlashFilter
 from scenedetect.detectors import ContentDetector
 from scenedetect.output.video import _DEFAULT_FFMPEG_ARGS
+from scenedetect.platform import DEBUG_MODE
 from scenedetect.scene_manager import Interpolation
 
 PYAV_THREADING_MODES = ["NONE", "SLICE", "FRAME", "AUTO"]
@@ -763,7 +764,7 @@ def _load_from_disk(self, path=None):
                 config_file_contents = config_file.read()
             config.read_string(config_file_contents, source=path)
         except (ConfigParserError, OSError) as ex:
-            if __debug__:
+            if DEBUG_MODE:
                 raise
             raise ConfigLoadFailure(self._init_log, reason=ex) from None
         # At this point the config file syntax is correct, but we need to still validate

scenedetect/_cli/context.py

@@ -34,7 +34,7 @@
     ThresholdDetector,
 )
 from scenedetect.output import is_ffmpeg_available, is_mkvmerge_available
-from scenedetect.platform import init_logger
+from scenedetect.platform import DEBUG_MODE, init_logger
 from scenedetect.scene_manager import SceneManager
 from scenedetect.stats_manager import StatsManager
 from scenedetect.video_stream import FrameRateUnavailable, VideoOpenFailure, VideoStream
@@ -351,7 +351,7 @@ def get_detect_content_params(
             try:
                 weights = ContentDetector.Components(*weights)
             except ValueError as ex:
-                if __debug__:
+                if DEBUG_MODE:
                     raise
                 logger.debug(str(ex))
                 raise click.BadParameter(str(ex), param_hint="weights") from None
@@ -383,7 +383,7 @@ def get_detect_adaptive_params(
             try:
                 weights = ContentDetector.Components(*weights)
             except ValueError as ex:
-                if __debug__:
+                if DEBUG_MODE:
                     raise
                 logger.debug(str(ex))
                 raise click.BadParameter(str(ex), param_hint="weights") from None
@@ -543,15 +543,15 @@ def _open_video_stream(
   Duration:     {duration_str}""")
 
         except FrameRateUnavailable as ex:
-            if __debug__:
+            if DEBUG_MODE:
                 raise
             raise click.BadParameter(
                 "Failed to obtain frame rate for input video. Manually specify frame rate with the"
                 " -f/--frame-rate option, or try re-encoding the file.",
                 param_hint="-i/--input",
             ) from ex
         except VideoOpenFailure as ex:
-            if __debug__:
+            if DEBUG_MODE:
                 raise
             raise click.BadParameter(
                 "Failed to open input video{}: {}".format(
@@ -560,7 +560,7 @@ def _open_video_stream(
                 param_hint="-i/--input",
             ) from ex
         except OSError as ex:
-            if __debug__:
+            if DEBUG_MODE:
                 raise
             raise click.BadParameter(
                 f"Input error:\n\n\t{ex!s}\n", param_hint="-i/--input"

scenedetect/platform.py

@@ -32,6 +32,20 @@
 """Type hint for filesystem paths. Accepts a `str` or any object implementing :class:`os.PathLike`
 (e.g. :class:`pathlib.Path`)."""
 
+DEBUG_MODE: bool = os.environ.get("SCENEDETECT_DEBUG", "").strip().lower() not in (
+    "",
+    "0",
+    "false",
+    "no",
+    "off",
+)
+"""True when the `SCENEDETECT_DEBUG` environment variable is set to a truthy value
+(`1`, `true`, `yes`, `on`, etc.); False when unset or set to `0`/`false`/`no`/`off`/empty.
+Use this to gate behavior intended only for development - e.g. re-raising unhandled
+exceptions for debuggers/pytest instead of logging gracefully and exiting. Default-off so
+end users on any install path (pip, pipx, the Windows .exe) get clean error output; pytest
+opts in via `tests/conftest.py`."""
+
 ##
 ## tqdm Library
 ##
@@ -302,70 +316,89 @@ def get_mkvmerge_version() -> str | None:
     return output.splitlines()[0]
 
 
+def _query_package_version(dist_name: str, fallback_module: str | None) -> str | None:
+    """Return version of an installed package, querying PyPI metadata first then
+    falling back to the module's `__version__` attribute when metadata is missing.
+
+    PyInstaller bundles ship modules but not the `.dist-info` directories that
+    `importlib.metadata` reads, so the fallback is required for frozen builds.
+    Returns None when the package isn't installed.
+    """
+    try:
+        return importlib.metadata.version(dist_name)
+    except importlib.metadata.PackageNotFoundError:
+        pass
+    if fallback_module is None:
+        return None
+    try:
+        module = importlib.import_module(fallback_module)
+    except ModuleNotFoundError:
+        return None
+    return getattr(module, "__version__", None)
+
+
 def get_system_version_info() -> str:
     """Get the system's operating system, Python, packages, and external tool versions.
     Useful for debugging or filing bug reports.
 
     Used for the `scenedetect version -a` command.
     """
-    output_template = "{:<16} {}"
     line_separator = "-" * 60
     not_found_str = "Not Installed"
     out_lines = []
 
-    # System (Python, OS)
-    output_template = "{:<16} {}"
-    out_lines += ["System Info", line_separator]
-    out_lines += [
-        output_template.format(name, version)
-        for name, version in (
-            ("OS", f"{platform.platform()}"),
-            ("Python", f"{platform.python_implementation()} {platform.python_version()}"),
-            ("Architecture", " + ".join(platform.architecture())),
-        )
-    ]
+    system_info = (
+        ("OS", f"{platform.platform()}"),
+        ("Python", f"{platform.python_implementation()} {platform.python_version()}"),
+        ("Architecture", " + ".join(platform.architecture())),
+    )
 
-    # Third-Party Packages: queried via PyPI distribution names. `cv2` is exposed by either
-    # `opencv-python` or `opencv-python-headless` - both are listed so whichever is installed
-    # gets reported. `scenedetect` is read from the package attribute since it must report a
-    # version even when run uninstalled (e.g. from a source checkout). The import is deferred
-    # to avoid a circular import at module load time.
+    # Third-Party Packages: queried via PyPI distribution names with a module-attribute
+    # fallback. PyInstaller bundles ship the modules but not the `.dist-info` metadata
+    # directories, so `importlib.metadata.version()` alone reports "Not Installed" for
+    # every package in a frozen build; reading `module.__version__` recovers the version
+    # there. `scenedetect` is read from the package attribute since it must report a
+    # version even when run uninstalled (e.g. from a source checkout). The import is
+    # deferred to avoid a circular import at module load time.
     from scenedetect import __version__ as scenedetect_version
 
-    out_lines += ["", "Packages", line_separator]
-    out_lines.append(output_template.format("scenedetect", scenedetect_version))
-    third_party_distributions = (
-        "av",
-        "click",
-        "opencv-python",
-        "opencv-python-headless",
-        "imageio",
-        "imageio-ffmpeg",
-        "moviepy",
-        "numpy",
-        "platformdirs",
-        "tqdm",
+    # (dist_name, fallback_module_name). Module fallback is only used when metadata is
+    # missing, so the metadata path still distinguishes `opencv-python` vs
+    # `opencv-python-headless` in source installs. In the frozen Windows build only
+    # `opencv-python-headless` is shipped, so `cv2` is attributed to that row alone.
+    third_party_packages = (
+        ("av", "av"),
+        ("click", "click"),
+        ("opencv-python", None),
+        ("opencv-python-headless", "cv2"),
+        ("imageio", "imageio"),
+        ("imageio-ffmpeg", "imageio_ffmpeg"),
+        ("moviepy", "moviepy"),
+        ("numpy", "numpy"),
+        ("platformdirs", "platformdirs"),
+        ("tqdm", "tqdm"),
     )
-    for dist_name in third_party_distributions:
-        try:
-            out_lines.append(
-                output_template.format(dist_name, importlib.metadata.version(dist_name))
-            )
-        except importlib.metadata.PackageNotFoundError:
-            out_lines.append(output_template.format(dist_name, not_found_str))
-
-    # External Tools
-    out_lines += ["", "Tools", line_separator]
+    package_versions = [("scenedetect", scenedetect_version)] + [
+        (dist_name, _query_package_version(dist_name, fallback_module) or not_found_str)
+        for dist_name, fallback_module in third_party_packages
+    ]
 
-    tool_version_info = (
-        ("ffmpeg", get_ffmpeg_version()),
-        ("mkvmerge", get_mkvmerge_version()),
+    tool_versions = (
+        ("ffmpeg", get_ffmpeg_version() or not_found_str),
+        ("mkvmerge", get_mkvmerge_version() or not_found_str),
     )
 
-    for tool_name, tool_version in tool_version_info:
-        out_lines.append(
-            output_template.format(tool_name, tool_version if tool_version else not_found_str)
-        )
+    # Size the label column to the longest label across every section so all three tables
+    # align consistently - `opencv-python-headless` exceeds the previous fixed width of 16.
+    label_width = max(len(name) for name, _ in (*system_info, *package_versions, *tool_versions))
+    output_template = f"{{:<{label_width}}} {{}}"
+
+    out_lines += ["System Info", line_separator]
+    out_lines += [output_template.format(name, value) for name, value in system_info]
+    out_lines += ["", "Packages", line_separator]
+    out_lines += [output_template.format(name, value) for name, value in package_versions]
+    out_lines += ["", "Tools", line_separator]
+    out_lines += [output_template.format(name, value) for name, value in tool_versions]
 
     return "\n".join(out_lines)
 

tests/conftest.py

@@ -32,6 +32,12 @@
 
 import pytest
 
+# Surface unhandled exceptions and KeyboardInterrupt as raw tracebacks during tests so pytest
+# (and any debugger) sees the original failure instead of the logger-formatted output the CLI
+# uses for end users. Read by `scenedetect.platform.DEBUG_MODE`. `setdefault` lets a developer
+# override (e.g. `SCENEDETECT_DEBUG=` to mimic end-user behavior in a specific test run).
+os.environ.setdefault("SCENEDETECT_DEBUG", "1")
+
 #
 # Helper Functions
 #

website/pages/changelog.md

@@ -687,6 +687,7 @@ Care was taken to minimize changes for most common API uses, however more advanc
 - [bugfix] `detect-threshold` cut frame numbers are now backend-deterministic; previously the cut could differ by 1 frame between PyAV and OpenCV when the fade midpoint landed on a `.5` rounding boundary (PyAV uses sub-microsecond PTS, OpenCV uses millisecond-truncated `CAP_PROP_POS_MSEC`)
 - [breaking] Remove deprecated `-d`/`--min-delta-hsv` option from `detect-adaptive` command (use `-c`/`--min-content-val` instead)
 - [breaking] Rename `-f/--framerate` to `-f/--frame-rate` as part of VFR overhaul (legacy `--framerate` form is preserved as a hidden alias but will be removed in v0.8)
+- [general] Support `SCENEDETECT_DEBUG` environment variable to control how exceptions and debugging are handled. Unhandled exceptions and `Ctrl+C` now produce a logger-formatted error message and exit cleanly with code 1 instead of dumping a raw Python traceback. Set `SCENEDETECT_DEBUG=1` to ensure all exceptions are re-raised instead of being logged. In both cases, the program will exit with a non-zero exit code.
 
 ### API Changes
 
@@ -765,3 +766,5 @@ Care was taken to minimize changes for most common API uses, however more advanc
     - tqdm 4.67.1 -> 4.67.3
     - ffmpeg 8.0 -> 8.1
  - [general] Reduced size of Windows distribution without affecting functionality
+ - [bugfix] Fix `scenedetect version` reporting `av`, `opencv-python-headless`, `platformdirs`, `click`, `numpy`, and `tqdm` as "Not Installed" in the bundled distribution (PyInstaller does not ship `.dist-info` directories by default, so `importlib.metadata` lookups failed at runtime)
+ - [bugfix] Pressing `Ctrl+C` during scene detection in the bundled distribution now exits cleanly instead of surfacing the PyInstaller bootloader traceback