DVR-Scan-Headless 1.8.2__tar.gz → 2.0__tar.gz

dvr_scan_headless-2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: dvr-scan-headless
+Version: 2.0
+Summary: Tool for finding and extracting motion events in video files (e.g. security camera footage).
+Author-email: Brandon Castellano <brandon248@gmail.com>
+License: BSD-2-Clause
+Project-URL: Bug Tracker, https://github.com/Breakthrough/DVR-Scan/issues
+Project-URL: Documentation, https://www.dvr-scan.com/docs
+Project-URL: Homepage, https://www.dvr-scan.com/
+Project-URL: Repository, https://github.com/Breakthrough/DVR-Scan
+Keywords: analysis,computer-vision,video
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Multimedia :: Video :: Non-Linear Editor
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: scenedetect-headless[pyav]~=0.7.2
+Requires-Dist: av
+Requires-Dist: tqdm
+Requires-Dist: pillow
+Requires-Dist: opencv-contrib-python-headless
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+![DVR-Scan](https://www.dvr-scan.com/assets/dvr-scan-logo.png)
+
+:vhs: Find and extract motion events in videos.
+
+------------------------------------------------
+
+### Latest Release: v2.0 (November 8, 2026)
+
+**Website**: [dvr-scan.com](https://www.dvr-scan.com)
+
+**User Guide**: [dvr-scan.com/guide](https://www.dvr-scan.com/guide/)
+
+**Documentation**: [dvr-scan.com/docs](https://www.dvr-scan.com/docs/)
+
+**Discord**: [discord.gg/69kf6f2Exb](https://discord.gg/69kf6f2Exb)
+
+------------------------------------------------------
+
+DVR-Scan is a command-line application that **automatically detects motion events in video files** (e.g. security camera footage).  DVR-Scan looks for areas in footage containing motion, and saves each event to a separate video clip.  DVR-Scan is free and open-source software, and works on Windows, Linux, and Mac.
+
+## Quick Install
+
+    pip install dvr-scan --upgrade
+
+Windows builds (installer + portable) are also available on [the Downloads page](https://www.dvr-scan.com/download/).
+
+## Quickstart (UI)
+
+Start DVR-Scan (run `dvr-scan-app` or click the app shortcut). The Scan Wizard walks you through each step: add your input videos, pick a preset, choose where to save the output, and hit **Start Scan**:
+
+<img alt="scan wizard" src="https://www.dvr-scan.com/assets/app-wizard-videos.jpg" width="480"/>
+
+See the [User Guide](https://www.dvr-scan.com/guide/) for a more comprehensive overview.
+
+## Quickstart (CLI)
+
+Scan `video.mp4` (separate clips for each event):
+
+    dvr-scan -i video.mp4
+
+Select a region to scan using [the region editor](https://www.dvr-scan.com/guide/):
+
+    dvr-scan -i video.mp4 -r
+
+<img alt="example of region editor" src="https://www.dvr-scan.com/assets/region-editor-mask.jpg" width="480"/>
+
+Select a region to scan using command line (list of points as X Y):
+
+    dvr-scan -i video.mp4 -a 50 50 100 50 100 100 100 50
+
+Draw boxes around motion:
+
+    dvr-scan -i video.mp4 -bb
+
+<img alt="example of bounding boxes" src="https://www.dvr-scan.com/assets/bounding-box.gif" width="480"/>
+
+Use `ffmpeg` to extract events:
+
+    dvr-scan -i video.mp4 -m ffmpeg
+
+See [the documentation](https://www.dvr-scan.com/docs) for a complete list of all command-line and configuration file options which can be set. You can also type `dvr-scan --help` for an overview of command line options. Some program options can also be set [using a config file](https://www.dvr-scan.com/docs/#config-file).
+
+------------------------------------------------
+
+Copyright © 2016-2026 Brandon Castellano. All rights reserved.
+Licensed under BSD 2-Clause (see the LICENSE file for details).

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/README.md

@@ -1,10 +1,10 @@
-![DVR-Scan Logo](https://raw.githubusercontent.com/Breakthrough/DVR-Scan/main/docs/assets/dvr-scan-logo.png)
+![DVR-Scan](https://www.dvr-scan.com/assets/dvr-scan-logo.png)
 
 :vhs: Find and extract motion events in videos.
 
 ------------------------------------------------
 
-### Latest Release: v1.8.2 (January 18, 2026)
+### Latest Release: v2.0 (November 8, 2026)
 
 **Website**: [dvr-scan.com](https://www.dvr-scan.com)
 
@@ -26,9 +26,9 @@ Windows builds (installer + portable) are also available on [the Downloads page]
 
 ## Quickstart (UI)
 
-Start DVR-Scan (run `dvr-scan-app` or click the app shortcut), **Add** your input videos, and hit **Start**:
+Start DVR-Scan (run `dvr-scan-app` or click the app shortcut). The Scan Wizard walks you through each step: add your input videos, pick a preset, choose where to save the output, and hit **Start Scan**:
 
-<img alt="main app window" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.8/docs/assets/app-main-window.jpg" width="480"/>
+<img alt="scan wizard" src="https://www.dvr-scan.com/assets/app-wizard-videos.jpg" width="480"/>
 
 See the [User Guide](https://www.dvr-scan.com/guide/) for a more comprehensive overview.
 
@@ -42,7 +42,7 @@ Select a region to scan using [the region editor](https://www.dvr-scan.com/guide
 
     dvr-scan -i video.mp4 -r
 
-<img alt="example of region editor" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.8/docs/assets/region-editor-mask.jpg" width="480"/>
+<img alt="example of region editor" src="https://www.dvr-scan.com/assets/region-editor-mask.jpg" width="480"/>
 
 Select a region to scan using command line (list of points as X Y):
 
@@ -52,7 +52,7 @@ Draw boxes around motion:
 
     dvr-scan -i video.mp4 -bb
 
-<img alt="example of bounding boxes" src="https://raw.githubusercontent.com/Breakthrough/DVR-Scan/releases/1.8/docs/assets/bounding-box.gif" width="480"/>
+<img alt="example of bounding boxes" src="https://www.dvr-scan.com/assets/bounding-box.gif" width="480"/>
 
 Use `ffmpeg` to extract events:
 

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/dvr-scan.cfg

@@ -9,25 +9,34 @@
 #   Windows: C:/Users/%USERNAME%/AppData/Local/DVR-Scan/dvr-scan.cfg
 #
 #   Linux:   ~/.config/DVR-Scan/dvr-scan.cfg
-#            $XDG_CONFIG_HOME/dvr-scan.cfg
+#            ($XDG_CONFIG_HOME/DVR-Scan/dvr-scan.cfg if XDG_CONFIG_HOME is set)
 #
-#   Mac:     ~/Library/Preferences/DVR-Scan/dvr-scan.cfg
+#   macOS:   ~/Library/Application Support/DVR-Scan/dvr-scan.cfg
 #
 # Run `dvr-scan --help` to see the exact path on your system which will be
 # used (it will be listed under the help text for the -c/--config option).
 #
 
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+#  APPLICATION
+# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+# Which mode the DVR-Scan app (dvr-scan-app) starts in: WIZARD or ADVANCED.
+# The Scan Wizard provides a simplified step-by-step workflow, while Advanced
+# Mode shows all settings at once. If this option is not set, the app starts
+# in ADVANCED mode. Can also be changed from File -> Startup Mode in the app,
+# or overridden for one launch with `dvr-scan-app --startup-mode`. Has no
+# effect on the command line.
+startup-mode = WIZARD
+
+
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 #  INPUT
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
-# Which mode to use for decoding frames. Possible values are: OPENCV, PYAV,
+# Which mode to use for decoding frames. Possible values are: PYAV, OPENCV,
 # MOVIEPY.
-#input-mode = OPENCV
-
-# Use presentation time instead of frame number for timestamps. May improve
-# timestamp accuracy with videos and network streams that may skip frames.
-#use-pts = no
+#input-mode = PYAV
 
 # Integer factor to shrink video before processing. Values <= 1 have no effect.
 #downscale-factor = 0
@@ -38,6 +47,10 @@
 # Always show the region editor window (-r/--region-editor) before scanning.
 #region-editor = no
 
+# Load region data from a file. Each line must be a list of points in the
+# format specified by -a/--add-region. Each line is treated as a polygon.
+#load-region = regions.txt
+
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 #  OUTPUT
@@ -51,38 +64,75 @@
 #open-output-dir = yes
 
 # Method of generating output videos. Possible values are: SCAN_ONLY, OPENCV,
-# FFMPEG, COPY. Not all features are supported in FFMPEG/COPY mode.
-#output-mode = OPENCV
+# FFMPEG, COPY, ENCODE. The default (ENCODE) produces MP4 (H.264) output with
+# overlay and audio support, and requires ffmpeg (OPENCV is used as a fallback
+# if ffmpeg is missing). Not all features are supported in FFMPEG/COPY mode.
+#output-mode = ENCODE
+
+# Encoder parameters used when generating output files in ENCODE mode. Stream
+# mappings are generated automatically and must not be set here. If no -pix_fmt
+# is given, -pix_fmt yuv420p is added and odd frame sizes are padded to even.
+#encode-args = -c:v libx264 -preset veryfast -crf 22 -c:a aac
 
 # Arguments to add before the input when calling ffmpeg in output-mode FFMPEG
 # or COPY. Note that `-y` and `-nostdin` are always added.
 #ffmpeg-input-args = -v error
 
 # Encoder parameters used when generating output files in FFMPEG mode.
-#ffmpeg-output-args = -map 0 -c:v libx264 -preset fast -crf 21 -c:a aac -sn
+#ffmpeg-output-args = -map 0:v:0 -map 0:a? -map 0:s? -c:v libx264 -preset veryfast -crf 22 -c:a aac
 
 # Four-letter identifier of the encoder/video codec to use in OPENCV mode.
 # Possible values are: XVID, MP4V, MP42, H264
 #opencv-codec = XVID
 
+# Only perform motion detection without writing any files to disk. If set,
+# output-mode is ignored.
+#scan-only = no
+
+# Produce thumbnail image(s) for each event. Possible values are: HIGHSCORE
+# (saves the frame with the highest motion score).
+#thumbnails = HIGHSCORE
+
+# Format of event list printed at the end of a scan (this is exactly what is
+# output in quiet mode). Must be one of:
+#   parts:     start-end,start-end,... (syntax of `mkvmerge --split parts:`)
+#   timecodes: start,end,start,end,... (syntax of `mkvmerge --split timecodes:`)
+#   lines:     one start-end pair per line (accepted as file input)
+#timecode-list-format = timecodes
+
 
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 #  MOTION
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
+# Maximum number of motion events to detect before stopping the scan early
+# (0 for no limit).
+#max-events = 0
+
 # Amount of time which must have motion in each frame to trigger an event.
-#min-event-length = 2
+#min-event-length = 0.1s
+
+# Maximum length of a single event, including pre/post-event padding. Longer
+# events are split into consecutive events of at most this length (no padding
+# is added at a split; if motion continues the next event starts there).
+#max-event-length = 999999s
 
 # Amount of time to include before an event.
 #time-before-event = 1.5s
 
-# Amount of time to include after an event.
+# Amount of time to include after an event. Cannot be larger than merge-window.
 #time-post-event = 2.0s
 
-# Threshold representing amount of motion in a frame (or the ROI, if set) for
-# a motion event to be triggered. Lower values require less movement, and are
-# more sensitive to motion. If too high, some movement may not be detected,
-# while too low of a threshold can result in false detection events.
+# Merge groups of motion which occur less than this amount of time apart into
+# the same event. The default (auto) uses the same value as time-post-event,
+# which matches the behavior of previous versions.
+#merge-window = auto
+
+# Threshold representing amount of motion in a frame (or in the detection
+# regions, if set) for a motion event to be triggered. Lower values require
+# less movement, and are more sensitive to motion. If too high, some movement
+# may not be detected, while too low of a threshold can result in false
+# detection events.
 #threshold = 0.15
 
 
@@ -159,14 +209,14 @@
 # Enable/disable frame metrics overlay in top right of video frame.
 #frame-metrics = yes
 
-# Size of border around text, in pixels. Must be <= text-margin.
+# Padding between the text and the edge of its background box, in pixels.
 #text-border = 4
 
-# Size of margin around border, in pixels.
+# Margin between the background box and the edge of the frame, in pixels.
 #text-margin = 4
 
 # Font scale factor.
-#text-font-scale = 2.0
+#text-font-scale = 1.0
 
 # Thickness of font (integer values only).
 #text-font-thickness = 2
@@ -182,12 +232,13 @@
 #  LOGGING
 # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
-# Suppress all console output. Output can still be saved using
-# the -l/--logfile option.
+# Suppress all console output except for the final event list (see
+# timecode-list-format). Output can still be saved using the --logfile option.
 #quiet-mode = no
 
-# Verbosity of console output (debug, info, warning, error).
-# If set to debug, overrides quiet-mode unless set via command line.
+# Verbosity of log output (debug, info, warning, error). Applies to the console
+# and to --logfile. If quiet-mode is enabled, nothing except the final event
+# list is printed to the console regardless of verbosity.
 #verbosity = info
 
 # Automatically save rolling logs. Useful for bug reports.

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/dvr_scan/__init__.py

@@ -24,7 +24,7 @@ main modules under `dvr_scan` are organized as follows:
 
 There are also a few helper modules:
 
-  ``video_joiner``: concatenates multiple input videos
+  ``video_input``: opens one or more input videos as a single contiguous stream
 
   ``opencv_loader``: helper for resolving dynamic libraries used by OpenCV
 
@@ -35,7 +35,7 @@ import pkgutil
 import sys
 
 # Used for module/distribution identification.
-__version__ = "1.8.2"
+__version__ = "2.0"
 
 # Handle loading OpenCV. This **MUST** be first before any other DVR-Scan or third-party
 # packages are imported which might attempt to import the `cv2` module.

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/dvr_scan/__main__.py

@@ -65,6 +65,12 @@ def main():
             logger.critical("Error (Not Implemented): %s", str(ex), exc_info=show_traceback)
             if debug_mode:
                 raise
+        except (OSError, RuntimeError) as ex:
+            # I/O errors (e.g. an unwritable output path) and ffmpeg failures: the message
+            # is enough to act on, so only show the traceback in debug mode.
+            logger.critical("Error: %s", str(ex), exc_info=show_traceback)
+            if debug_mode:
+                raise
         except Exception as ex:
             logger.critical("Critical Error: %s", str(ex), exc_info=True)
             if debug_mode:

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/dvr_scan/app/__main__.py

@@ -21,6 +21,13 @@ from scenedetect import VideoOpenFailure
 import dvr_scan
 from dvr_scan import get_license_info
 from dvr_scan.app.application import Application
+from dvr_scan.app.startup import (
+    STARTUP_MODE_OPTION,
+    has_prior_logs,
+    normalize_startup_mode,
+    resolve_default_startup_mode,
+    save_startup_mode,
+)
 from dvr_scan.config import CHOICE_MAP, USER_CONFIG_FILE_PATH, ConfigLoadFailure, ConfigRegistry
 from dvr_scan.shared import (
     ScanSettings,
@@ -40,6 +47,13 @@ EXIT_ERROR: int = 1
 LOGFILE_PATH = logfile_path(name_prefix="dvr-scan-app")
 
 
+def _startup_mode_type(value: str) -> str:
+    """argparse type for `--startup-mode`: accepts the legacy alias "classic" (normalized
+    to "advanced") in addition to the values in CHOICE_MAP, any case."""
+    check = string_type_check(CHOICE_MAP[STARTUP_MODE_OPTION], False, "mode")
+    return check(normalize_startup_mode(value))
+
+
 def get_cli_parser():
     parser = argparse.ArgumentParser(
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
@@ -101,6 +115,16 @@ def get_cli_parser():
         help=("Ignore loading the user config file if present."),
     )
 
+    parser.add_argument(
+        "--startup-mode",
+        metavar="mode",
+        type=_startup_mode_type,
+        help=(
+            "Mode to start the application in. Must be one of: %s. Overrides the startup-mode "
+            "config option for this launch only." % (", ".join(CHOICE_MAP["startup-mode"]),)
+        ),
+    )
+
     parser.add_argument(
         "--debug",
         action="store_true",
@@ -178,20 +202,63 @@ def main():
         logger.debug("Error loading config file:", exc_info=config_load_error)
         # Intentionally suppress the exception in release mode since we've already logged the
         # failure reason to the user above. We can now exit with an error code.
-        errors = [message for (severity, message) in init_log if severity >= logging.ERROR]
+        errors = "\n".join(message for (severity, message) in init_log if severity >= logging.ERROR)
         tkinter.messagebox.showerror(
             title="DVR-Scan Startup Error",
-            message=f"Error loading config file. Reason:\n\n{'\n'.join(errors)}",
+            message=f"Error loading config file. Reason:\n\n{errors}",
         )
         raise SystemExit(1)
 
     show_traceback = getattr(logging, settings.get("verbosity").upper()) == logging.DEBUG
     # TODO: Use Python __debug__ mode instead of hard-coding as config option.
     debug_mode = settings.get("debug")
+
+    # Resolve the default startup mode (wizard or advanced). The first-run heuristic only
+    # applies when the user config is in play and no file was given explicitly, since it
+    # may write the result to the user config file.
+    allow_heuristic = not args.ignore_user_config and not hasattr(args, "config")
+    default_startup_mode, persist_startup_mode = resolve_default_startup_mode(
+        config,
+        user_config_exists=USER_CONFIG_FILE_PATH.exists(),
+        prior_logs=has_prior_logs(LOGFILE_PATH.parent, exclude=LOGFILE_PATH),
+        allow_heuristic=allow_heuristic,
+    )
+    if persist_startup_mode:
+        try:
+            path = save_startup_mode(default_startup_mode)
+            logger.debug("first run: saved startup-mode = %s to %s", default_startup_mode, path)
+        except (OSError, UnicodeError) as ex:
+            logger.warning("Failed to save startup mode to user config file: %s", ex)
+    startup_mode = (
+        normalize_startup_mode(args.startup_mode)
+        if hasattr(args, "startup_mode")
+        else default_startup_mode
+    )
+    # The File > Startup Mode menu shows and edits the value in the user config file. With
+    # -c or --ignore-user-config that is not the config we launched from, so read it here
+    # (falling back to the program default if the user config is missing or invalid).
+    menu_startup_mode = default_startup_mode
+    if not allow_heuristic:
+        try:
+            user_config = ConfigRegistry()
+            user_config.load(log_level=logging.DEBUG)
+            menu_startup_mode = normalize_startup_mode(user_config.get(STARTUP_MODE_OPTION))
+        except ConfigLoadFailure:
+            menu_startup_mode = normalize_startup_mode(ConfigRegistry().get(STARTUP_MODE_OPTION))
+    logger.debug(
+        "startup mode: %s (default: %s, user config: %s)",
+        startup_mode,
+        default_startup_mode,
+        menu_startup_mode,
+    )
+
     with logging_redirect_tqdm(loggers=[logger]):
         try:
             app = Application(
-                settings=settings, initial_videos=args.input if hasattr(args, "input") else []
+                settings=settings,
+                initial_videos=args.input if hasattr(args, "input") else [],
+                startup_mode=startup_mode,
+                default_startup_mode=menu_startup_mode,
             )
             app.run()
 

{dvr_scan_headless-1.8.2 → dvr_scan_headless-2.0}/dvr_scan/app/about_window.py

@@ -27,7 +27,8 @@ from dvr_scan.platform import get_system_version_info
 
 TITLE = "About DVR-Scan"
 COPYRIGHT = (
-    f"DVR-Scan {dvr_scan.__version__}\n\nCopyright © Brandon Castellano.\nAll rights reserved."
+    f"DVR-Scan {dvr_scan.__version__}\n\n"
+    "Copyright \N{COPYRIGHT SIGN} Brandon Castellano.\nAll rights reserved."
 )