diff --git a/docs/changelog.md b/docs/changelog.md index 335a581..d19ed78 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -7,7 +7,11 @@ ### 2.1 (In Development) - * No changes yet. + * [feature] New `time-code-start` config option and `--time-code-start` flag show the date and time of recording in the timecode overlay (`-tc`) [#285](https://github.com/Breakthrough/DVR-Scan/issues/285) + * `filename` reads the start time of each input from its file name (e.g. `20261116233730.avi`), `modified` uses the file modified time minus the duration, or give the start time of the first input as `YYYY-MM-DD HH:MM:SS` (which shifts dated file names to correct clock or time zone errors, or continues sequentially for undated files) + * In the app, set it with Timecode Start in the output options + * [bugfix] A start time at or after the end of the input, or an end time that is not after the start time, now gives an error. Before, the scan read 0 frames and found no events with no warning [#285](https://github.com/Breakthrough/DVR-Scan/issues/285) + * [bugfix] The Date column of the app input list now shows the file modified time instead of the creation time. On Windows, a copy (e.g. from an SD card) sets the creation time to the time of the copy [#285](https://github.com/Breakthrough/DVR-Scan/issues/285) ### 2.0 (2026-11-08) diff --git a/docs/docs.md b/docs/docs.md index b58aeea..48ab00a 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -324,6 +324,10 @@ All time values can be given as a timecode (`HH:MM:SS` or `HH:MM:SS.nnn`), in se *
-tc, --time-code
Draw time code of each frame on the top left corner.
Text properties (e.g. color, font size, margin) can be set with a [config file](#overlays_1). + *
--time-code-start
Show the date and time of recording in the time code (`-tc`) instead of the position in the video. +
`filename`: read the start time of each input from its file name (e.g. `20261116233730.avi` or `VID_20261116_233730.mp4`). `modified`: use the file modified time minus the duration of the video. Or give the start time of the first input, e.g. `--time-code-start "2026-11-16 23:37:30"` (uses file name time differences for later inputs when present, otherwise assumes continuous recording). +
See the [`time-code-start`](#text-overlays) config option for details. + *
-fm, --frame-metrics
Draw frame metrics, including motion score, on the top right corner.
Text properties (e.g. color, font size, margin) can be set with a [config file](#config-file). @@ -733,6 +737,25 @@ Color values can be specified as either `(R,G,B)` or in hex as `0xFFFFFF`. Time ``` + *
time-code-start
+ Start time of the timecode overlay. If set, the timecode shows the date and time of recording instead of the position in the video. The time of each frame is the start time of its input video plus the position of the frame in that video. Times are local times, as the camera wrote them. + * `none`: show the position in the video. + * `filename`: read the start time of each input from its file name. The name must contain the date and time as `YYYYMMDDhhmmss`, with optional separators between the parts (e.g. `20261116233730.avi`, `VID_20261116_233730.mp4`, `2026-11-16_23-37-30.mp4`). If a file name has no date and time, the timecode shows the position in the video for that input. + * `modified`: use the file modified time minus the duration of the video. Many cameras set the modified time when a clip ends; cameras without a clock write a fixed date. A copy of the file usually keeps the modified time. + * A date and time as `YYYY-MM-DD HH:MM:SS`: the start time of the first input. If all input file names contain a date and time, later inputs are placed using the differences between their file name times. This corrects camera clock and time zone errors and allows gaps between clips within one power cycle (after a power loss, a camera clock may reset to a factory default time). If any file name has no date and time, later inputs continue from the first input as if the recording was continuous. + + The time can be wrong if the frame rate in the file is not the rate at which the camera recorded. If you save a fixed date and time in a preset or in the Default config file, it applies to all later scans until changed. + + ``` + time-code-start = none + ``` + + + ``` + time-code-start = filename + ``` + + *
frame-metrics
Enable frame metrics overlay: (`yes` or `no`). Draws frame metrics, including motion score, on top right of each frame. diff --git a/dvr-scan.cfg b/dvr-scan.cfg index d058944..f423500 100644 --- a/dvr-scan.cfg +++ b/dvr-scan.cfg @@ -206,6 +206,18 @@ startup-mode = WIZARD # Enable/disable timecode overlay in top-left of video frame. #time-code = yes +# Start time of the timecode overlay. Set it to show the date and time of +# recording instead of the position in the video: +# - filename: read the start time of each input from the file name +# (e.g. 20261116233730.avi or VID_20261116_233730.mp4). +# - modified: the file modified time minus the duration of the video. Many +# cameras set this when a clip ends; cameras without a clock write a fixed date. +# - YYYY-MM-DD HH:MM:SS: the start time of the first input. If all input file +# names contain a date and time, later inputs are placed using the differences +# between their file name times (one power cycle); otherwise later inputs +# continue from the first input as if the recording was continuous. +#time-code-start = none + # Enable/disable frame metrics overlay in top right of video frame. #frame-metrics = yes diff --git a/dvr_scan/app/application.py b/dvr_scan/app/application.py index 6af3a2e..0da2704 100644 --- a/dvr_scan/app/application.py +++ b/dvr_scan/app/application.py @@ -30,6 +30,7 @@ PADDING, SETTING_INPUT_WIDTH, MenuBar, + Tooltip, add_startup_mode_menu, fill_help_menu, fit_window_to_screen, @@ -68,6 +69,7 @@ from dvr_scan.scanner import OutputMode, Point from dvr_scan.shared import ScanSettings, finalize_output_names, resolve_output_mode from dvr_scan.subtractor import SubtractorCNT, SubtractorCudaMOG2 +from dvr_scan.wallclock import TIME_CODE_START_CHOICES, normalize_time_code_start WINDOW_TITLE = "DVR-Scan" LONG_SETTING_INPUT_WIDTH = 72 @@ -215,6 +217,13 @@ def __init__(self, root: tk.Widget): self._end_time_label = tk.Label(root, text="End Time") self._end_time = TimecodeEntry(root, "00:00:00.000") + # Times are positions in the video, not times of day (#285). + start_time_tip = "Position in the video to start the scan." + end_time_tip = "Position in the video to end the scan (0 = end of video)." + Tooltip(self._start_time_label, start_time_tip) + Tooltip(self._start_time.widget, start_time_tip) + Tooltip(self._end_time_label, end_time_tip) + Tooltip(self._end_time.widget, end_time_tip) ttk.Checkbutton( root, @@ -1136,6 +1145,28 @@ def clear_output_directory(): row=1, column=1, sticky=tk.W, padx=PADDING, pady=(PADDING, 0) ) + # Start time of the timecode: a choice, or a date and time that the user types. + time_code_start_tip = ( + "Show recording date and time in the timecode: choose none, filename, or modified," + " or type YYYY-MM-DD HH:MM:SS." + ) + time_code_start_label = tk.Label(self._opencv_options, text="Timecode Start") + time_code_start_label.grid( + row=1, column=2, sticky=EXPAND_HORIZONTAL, padx=PADDING, pady=(PADDING, 0) + ) + self._last_valid_time_code_start = str(CONFIG_MAP["time-code-start"]) + self._time_code_start = tk.StringVar(value=self._last_valid_time_code_start) + self._time_code_start_combo = ttk.Combobox( + self._opencv_options, + textvariable=self._time_code_start, + values=list(TIME_CODE_START_CHOICES), + ) + self._time_code_start_combo.grid( + row=1, column=3, sticky=EXPAND_HORIZONTAL, padx=PADDING, pady=(PADDING, 0) + ) + Tooltip(time_code_start_label, time_code_start_tip) + Tooltip(self._time_code_start_combo, time_code_start_tip) + tk.Label(self._opencv_options, text="Text Color").grid( row=2, column=0, sticky=EXPAND_HORIZONTAL, padx=PADDING, pady=(PADDING, 0) ) @@ -1319,6 +1350,7 @@ def _on_text_overlay(self): self._text_margin["state"] = state self._text_bg_color["state"] = state self._text_font_color["state"] = state + self._time_code_start_combo["state"] = tk.NORMAL if self._timecode.get() else tk.DISABLED def _on_bounding_box(self): state = tk.NORMAL if self._bounding_box.get() else tk.DISABLED @@ -1375,6 +1407,9 @@ def load(self, settings: ScanSettings): self._encode_args.set(settings.get("encode-args")) # Text Overlays self._timecode.set(settings.get("time-code")) + time_code_start = str(settings.get("time-code-start")) + self._time_code_start.set(time_code_start) + self._last_valid_time_code_start = time_code_start self._frame_metrics.set(settings.get("frame-metrics")) self._text_font_color.set(settings.get("text-font-color")) self._text_bg_color.set(settings.get("text-bg-color")) @@ -1390,6 +1425,23 @@ def load(self, settings: ScanSettings): self._bounding_box_thickness.set(settings.get("bounding-box-thickness")) self._on_mode_combo_selected() + def validate_time_code_start(self) -> str: + """Validate and normalize the Timecode Start field when active. + + Raises: + ValueError: Timecode overlay is enabled and the entered value is not valid. + """ + if ( + self._output_mode not in (OutputMode.OPENCV, OutputMode.ENCODE) + or not self._timecode.get() + ): + return self._last_valid_time_code_start + raw = self._time_code_start.get().strip() or "none" + normalized = normalize_time_code_start(raw) + self._last_valid_time_code_start = normalized + self._time_code_start.set(normalized) + return normalized + def save(self, settings: ScanSettings) -> ScanSettings: settings.set("output-mode", self._output_mode) if self._output_dir: @@ -1404,6 +1456,19 @@ def save(self, settings: ScanSettings) -> ScanSettings: settings.set("encode-args", self._encode_args.get()) # Text Overlays settings.set("time-code", self._timecode.get()) + raw_start = self._time_code_start.get().strip() or "none" + try: + normalized_start = normalize_time_code_start(raw_start) + self._last_valid_time_code_start = normalized_start + settings.set("time-code-start", normalized_start) + except ValueError: + # Keep the last valid value when the field is disabled so saved configs + # cannot be corrupted; keep the raw value when active so UI state diffs + # detect unsaved edits without throwing. + settings.set( + "time-code-start", + raw_start if self._timecode.get() else self._last_valid_time_code_start, + ) settings.set("frame-metrics", self._frame_metrics.get()) settings.set("text-font-color", self._text_font_color.get()) settings.set("text-bg-color", self._text_bg_color.get()) @@ -1776,6 +1841,8 @@ def _open_wizard(self, initial: bool = False): get_scan_overrides=self._input_area.scan_overrides, ) if not initial: + if not self._validate_ui_settings(): + return self._wizard.sync_from_settings( self._get_config_settings(), active_preset=self._active_preset ) @@ -1848,11 +1915,28 @@ def _destroy(self): self._root.after(0, lambda: self._root.destroy()) self._root.withdraw() + def _validate_ui_settings(self) -> bool: + """Validate editable UI fields before scanning, saving configs/presets, or switching + to Scan Wizard. Shows an error dialog and returns False on failure.""" + try: + self._output_area.validate_time_code_start() + except ValueError as ex: + tkinter.messagebox.showerror( + title="Invalid Setting", + message=str(ex), + parent=self._root, + ) + return False + return True + def _start_scan(self): # It should not be possible to start two scans in parallel with the current UI. # Once we start a scan, the scan window should grab input focus until it is closed. assert self._scan_window is None + if not self._validate_ui_settings(): + return + # TODO: Instead of just returning None below if the settings are invalid or we can't start # the scan (e.g. no input videos selected), we should throw an exception and catch it here. # We should then display a messagebox to the user indicating why the scan couldn't start. @@ -1942,6 +2026,8 @@ def _initialize(self, settings: ScanSettings): self._scan_area.load(settings) def _on_save_config(self): + if not self._validate_ui_settings(): + return save_path = tkinter.filedialog.asksaveasfilename( title="Save Config File...", filetypes=[("Config File", "*.cfg")], @@ -2009,6 +2095,8 @@ def _on_preset_selected(self, preset: presets.Preset): self._on_preset_applied(preset, config) def _on_save_preset(self): + if not self._validate_ui_settings(): + return name = tkinter.simpledialog.askstring( title="Save Preset", prompt="Preset name:", diff --git a/dvr_scan/app/common.py b/dvr_scan/app/common.py index c1f1863..d74b68a 100644 --- a/dvr_scan/app/common.py +++ b/dvr_scan/app/common.py @@ -126,6 +126,46 @@ def hide_modal(window: tk.Toplevel, focus: tk.Misc): focus.focus() +class Tooltip: + """A minimal hover tooltip, e.g. to label icon-only buttons.""" + + def __init__(self, widget: tk.Widget, text: str): + self._widget = widget + self._text = text + self._tip: ty.Optional[tk.Toplevel] = None + widget.bind("", self._show, add="+") + widget.bind("", self._hide, add="+") + widget.bind("", self._hide, add="+") + # Tear down a visible tip if the widget is hidden or destroyed while hovered. + widget.bind("", self._hide, add="+") + widget.bind("", self._hide, add="+") + + def _show(self, _event=None): + if self._tip is not None or not self._widget.winfo_exists(): + return + x = self._widget.winfo_rootx() + self._widget.winfo_width() // 2 + y = self._widget.winfo_rooty() + self._widget.winfo_height() + 2 + self._tip = tk.Toplevel(self._widget) + self._tip.wm_overrideredirect(True) + self._tip.wm_geometry(f"+{x}+{y}") + tk.Label( + self._tip, + text=self._text, + justify=tk.LEFT, + wraplength=320, + background="#ffffe0", + relief=tk.SOLID, + borderwidth=1, + padx=4, + pady=1, + ).pack() + + def _hide(self, _event=None): + if self._tip is not None: + self._tip.destroy() + self._tip = None + + class MenuBar: """A custom menubar built from `tk.Menubutton` headings so the top-level menus get a real hover highlight. The native Windows menubar (`toplevel["menu"] = ...`) exposes no diff --git a/dvr_scan/app/inputs.py b/dvr_scan/app/inputs.py index 02d04dd..12ab758 100644 --- a/dvr_scan/app/inputs.py +++ b/dvr_scan/app/inputs.py @@ -51,7 +51,7 @@ def parse_resolution(text: str) -> ty.Optional[ty.Tuple[int, int]]: def probe_video(path: str) -> ty.Optional[VideoInfo]: - """Open `path` and extract display metadata (duration, framerate, resolution, creation + """Open `path` and extract display metadata (duration, framerate, resolution, modified date), returning a `VideoInfo` or None if the video could not be opened. Errors are logged by `open_video`; callers decide how to surface a failure to the user.""" try: @@ -59,20 +59,21 @@ def probe_video(path: str) -> ty.Optional[VideoInfo]: except VideoOpenFailure: return None try: - # On Windows, ctime is creation time. On other systems, it may be the last - # metadata change time. - create_time = datetime.fromtimestamp(Path(path).stat().st_ctime) - create_time_str = create_time.strftime("%Y-%m-%d %H:%M:%S") - except OSError as ex: + # Use the modified time, not ctime. On Windows, ctime is the creation time of the + # file, so a copy (e.g. from an SD card) sets it to the time of the copy. A copy + # keeps the modified time, which many cameras set when a clip ends (#285). + modified_time = datetime.fromtimestamp(Path(path).stat().st_mtime) + modified_time_str = modified_time.strftime("%Y-%m-%d %H:%M:%S") + except (OSError, OverflowError, ValueError) as ex: logger.debug(f"Failed to stat {path}: {ex}") - create_time_str = "N/A" + modified_time_str = "N/A" return VideoInfo( path=str(Path(video.path).absolute()), name=Path(video.path).name, duration=video.duration.get_timecode(), framerate=f"{float(video.frame_rate):g}", resolution=f"{video.frame_size[0]} x {video.frame_size[1]}", - date=create_time_str, + date=modified_time_str, ) diff --git a/dvr_scan/app/video_list.py b/dvr_scan/app/video_list.py index a31cc7e..f6211b7 100644 --- a/dvr_scan/app/video_list.py +++ b/dvr_scan/app/video_list.py @@ -39,7 +39,7 @@ import tkinter.ttk as ttk import typing as ty -from dvr_scan.app.common import PADDING +from dvr_scan.app.common import PADDING, Tooltip from dvr_scan.app.inputs import ( VideoInfo, ask_video_paths, @@ -90,44 +90,6 @@ class _Row: text_labels: ty.List[tk.Label] -class _Tooltip: - """A minimal hover tooltip, used to label the icon-only toolbar buttons.""" - - def __init__(self, widget: tk.Widget, text: str): - self._widget = widget - self._text = text - self._tip: ty.Optional[tk.Toplevel] = None - widget.bind("", self._show, add="+") - widget.bind("", self._hide, add="+") - widget.bind("", self._hide, add="+") - # Tear down a visible tip if the button is destroyed while hovered. - widget.bind("", self._hide, add="+") - - def _show(self, _event=None): - if self._tip is not None or not self._widget.winfo_exists(): - return - x = self._widget.winfo_rootx() + self._widget.winfo_width() // 2 - y = self._widget.winfo_rooty() + self._widget.winfo_height() + 2 - self._tip = tk.Toplevel(self._widget) - self._tip.wm_overrideredirect(True) - self._tip.wm_geometry(f"+{x}+{y}") - tk.Label( - self._tip, - text=self._text, - justify=tk.LEFT, - background="#ffffe0", - relief=tk.SOLID, - borderwidth=1, - padx=4, - pady=1, - ).pack() - - def _hide(self, _event=None): - if self._tip is not None: - self._tip.destroy() - self._tip = None - - class VideoList: """Scrollable list of input videos with stacked metadata rows and a vertical icon toolbar. Built into `root`, mirroring the `InputArea` API used by the Scan Wizard.""" @@ -213,7 +175,7 @@ def _toolbar_button( ) -> ttk.Button: button = ttk.Button(parent, text=glyph, width=TOOLBAR_BUTTON_WIDTH, command=command) button.grid(row=row, column=0, pady=(0, PADDING)) - _Tooltip(button, tip) + Tooltip(button, tip) return button def _bind_mousewheel(self, widget: tk.Widget): @@ -294,7 +256,7 @@ def update(self, settings: ScanSettings) -> ty.Optional[ScanSettings]: def sort_by(self, col: str, descending: bool): """Reorder the list by metadata field `col` (one of the SORT_FIELDS column ids: - "#0" is the name, "date" is the creation date). Names sort case-insensitively; + "#0" is the name, "date" is the modified date). Names sort case-insensitively; date strings (YYYY-MM-DD HH:MM:SS) sort lexicographically, which is chronological.""" def key(iid: str) -> str: diff --git a/dvr_scan/app/widgets.py b/dvr_scan/app/widgets.py index 884c76c..c2e39bc 100644 --- a/dvr_scan/app/widgets.py +++ b/dvr_scan/app/widgets.py @@ -71,6 +71,10 @@ def __init__(self, widget: ttk.Widget, variable: tk.StringVar, value: str): # Expose grid method from underlying widget self.grid = widget.grid + @property + def widget(self) -> ttk.Widget: + return self._widget + def _normalize(self, text: str) -> str: raise NotImplementedError diff --git a/dvr_scan/cli.py b/dvr_scan/cli.py index 387c267..0e66572 100644 --- a/dvr_scan/cli.py +++ b/dvr_scan/cli.py @@ -26,6 +26,16 @@ string_type_check, timecode_type_check, ) +from dvr_scan.wallclock import normalize_time_code_start + + +def time_code_start_type(value: str) -> str: + """argparse type for --time-code-start (see `dvr_scan.wallclock`).""" + try: + return normalize_time_code_start(value) + except ValueError as ex: + raise argparse.ArgumentTypeError(str(ex)) from None + # In the CLI, -so/--scan-only is a different flag than -m/--output-mode, whereas in the # config file they are the same option. Therefore, we remove the scan only choice @@ -427,6 +437,21 @@ def get_cli_parser(user_config: ConfigRegistry): ), ) + parser.add_argument( + "--time-code-start", + metavar="start", + type=time_code_start_type, + help=( + "Show the date and time of recording in the time code (-tc). Set the start time of" + " each input from the file name (filename), or from the modified time of the file" + " minus its duration (modified). You can also give the start time of the first" + ' input as "YYYY-MM-DD HH:MM:SS" (uses file name time differences for later inputs' + " when all file names have timestamps, otherwise assumes continuous recording)." + " Default is none (show the position in the video).%s" + % user_config.get_help_string("time-code-start", show_default=False) + ), + ) + parser.add_argument( "-fm", "--frame-metrics", diff --git a/dvr_scan/config.py b/dvr_scan/config.py index 8a0a887..3e2cb0d 100644 --- a/dvr_scan/config.py +++ b/dvr_scan/config.py @@ -39,6 +39,7 @@ DEFAULT_FFMPEG_INPUT_ARGS, DEFAULT_FFMPEG_OUTPUT_ARGS, ) +from dvr_scan.wallclock import normalize_time_code_start # Backwards compatibility for config options that were renamed/replaced. MIGRATED_CONFIG_OPTION: ty.Dict[str, str] = { @@ -117,6 +118,32 @@ def from_config(config_value: str, default: "TimecodeValue") -> "TimecodeValue": ) from ex +class TimeCodeStartValue(ValidatedValue): + """Validator for `time-code-start`: `none`, `filename`, `modified`, or a date and time + (YYYY-MM-DD HH:MM:SS). Stores the value as a string.""" + + def __init__(self, value: str = "none"): + # Ensure value is valid and normalize keyword choices to lowercase. + self._value = normalize_time_code_start(value) + + @property + def value(self) -> str: + return self._value + + def __repr__(self) -> str: + return self._value + + def __str__(self) -> str: + return self._value + + @staticmethod + def from_config(config_value: str, default: "TimeCodeStartValue") -> "TimeCodeStartValue": + try: + return TimeCodeStartValue(config_value) + except ValueError as ex: + raise OptionParseFailure(str(ex)) from ex + + class MergeWindowValue(ValidatedValue): """Validator for the merge-window option: a timecode value in frames (1234), seconds (123.4s), or HH:MM:SS, or the string "auto" to use time-post-event. @@ -510,6 +537,7 @@ def set_user_config_option(option: str, value: str, path: ty.Optional[Path] = No # Overlays # Text Overlays "time-code": False, + "time-code-start": TimeCodeStartValue(), "frame-metrics": False, "text-border": 4, "text-margin": 4, diff --git a/dvr_scan/scanner.py b/dvr_scan/scanner.py index 5237195..612ffc0 100644 --- a/dvr_scan/scanner.py +++ b/dvr_scan/scanner.py @@ -57,6 +57,7 @@ from dvr_scan.region import Point, Size, bound_point, load_regions, save_regions from dvr_scan.subtractor import SubtractorCNT, SubtractorCudaMOG2, SubtractorMOG2 from dvr_scan.video_input import VideoStreamConcat, open_input +from dvr_scan.wallclock import WallClock if HAS_TKINTER and HAS_PILLOW: from dvr_scan.app.region_editor import RegionEditor @@ -164,6 +165,7 @@ def __init__( # Overlay Parameters (set_overlays) self._timecode_overlay = None # -tc/--time-code, None or TextOverlay + self._wall_clock = None # --time-code-start, None or WallClock self._metrics_overlay = None # -fm/--frame-metrics, None or TextOverlay self._bounding_box = None # -bb/--bounding-box, None or BoundingBoxOverlay @@ -312,15 +314,23 @@ def set_overlays( timecode_overlay: ty.Optional[TextOverlay] = None, metrics_overlay: ty.Optional[TextOverlay] = None, bounding_box: ty.Optional[BoundingBoxOverlay] = None, + time_code_start: str = "none", ): """Sets options to use if/when drawing overlays on the resulting frames. Arguments: - draw_timecode: If True, draw a timecode (presentation time) on each frame. - bounding_box_smoothing: Value to use for temporal smoothing (in time) for drawing a - bounding box containing all detected motion in each frame. If None, no box will - be drawn. If <= 1, smoothing will be disabled. + timecode_overlay: If set, draw a timecode (presentation time) on each frame. + metrics_overlay: If set, draw the frame number and motion score on each frame. + bounding_box: If set, draw a box around the area with motion in each frame. + time_code_start: Start time for the timecode overlay (see `dvr_scan.wallclock`). + If not `none`, the timecode shows the date and time of recording. + + Raises: + ValueError: `time_code_start` is not a valid value. """ + self._wall_clock = ( + WallClock.create(self._input, time_code_start) if timecode_overlay else None + ) self._timecode_overlay = timecode_overlay self._metrics_overlay = metrics_overlay self._bounding_box = bounding_box @@ -518,6 +528,36 @@ def _handle_regions(self) -> bool: logger.debug("no regions selected") return True + def _check_time_range(self): + """Raise ValueError if the start/end time selects no frames of the input. + + Without this check, the scan reads 0 frames and reports no events, with no error. + Users can then think that the start time is a schedule that the scan waits for (#285). + """ + durations = [self._input.source_duration(i) for i in range(len(self._input.sources))] + if ( + self._start_time is not None + and all(d > 0 for d in durations) + and self._start_time.seconds >= float(sum(durations)) + ): + input_duration = float(sum(durations)) + raise ValueError( + f"Start time {self._start_time.get_timecode()} is not before the end of the" + f" input ({FrameTimecode(input_duration, 1000.0).get_timecode()}). The start" + " time is a position in the video, not a time of day." + ) + if self._end_time is not None: + effective_start = self._start_time.seconds if self._start_time is not None else 0.0 + if self._end_time.seconds <= effective_start: + if self._start_time is not None: + raise ValueError( + f"End time {self._end_time.get_timecode()} is not after start time" + f" {self._start_time.get_timecode()}." + ) + raise ValueError( + f"End time {self._end_time.get_timecode()} must be greater than 00:00:00.000." + ) + @property def frames_remaining(self) -> int: num_frames = self._input.total_frames @@ -572,6 +612,8 @@ def scan(self) -> ty.Optional[DetectionResult]: in_motion_event = False frames_processed = 0 + self._check_time_range() + # Seek to starting position if required. When a start time is set, use it directly # as the scan start: after a seek, the backend's reported position lags the first # frame that will be decoded by one frame. @@ -1257,7 +1299,8 @@ def _draw_overlays( use_shift=True, ): if self._timecode_overlay is not None: - self._timecode_overlay.draw(frame, text=timecode.get_timecode()) + text = self._wall_clock.get_text(timecode) if self._wall_clock else None + self._timecode_overlay.draw(frame, text=text or timecode.get_timecode()) if self._metrics_overlay is not None: to_display = "Frame: %04d\nScore: %3.2f" % ( timecode.frame_num, diff --git a/dvr_scan/shared/__init__.py b/dvr_scan/shared/__init__.py index ea72652..1749444 100644 --- a/dvr_scan/shared/__init__.py +++ b/dvr_scan/shared/__init__.py @@ -241,10 +241,18 @@ def init_scanner( smoothing=smoothing, ) + cli_time_code_start = getattr(settings.args, "time_code_start", None) + if ( + timecode_overlay is None + and cli_time_code_start is not None + and str(cli_time_code_start).strip().lower() != "none" + ): + logger.warning("--time-code-start has no effect without -tc/--time-code.") scanner.set_overlays( timecode_overlay=timecode_overlay, metrics_overlay=metrics_overlay, bounding_box=bounding_box, + time_code_start=settings.get("time-code-start"), ) scanner.set_detection_params( diff --git a/dvr_scan/video_input.py b/dvr_scan/video_input.py index 1c0676d..b294e25 100644 --- a/dvr_scan/video_input.py +++ b/dvr_scan/video_input.py @@ -20,13 +20,16 @@ convenience properties used by the scanner. """ +import bisect import logging +import threading import typing as ty from dataclasses import dataclass from fractions import Fraction from pathlib import Path import av +from scenedetect import FrameTimecode from scenedetect.backends import AVAILABLE_BACKENDS from scenedetect.backends.concat import SourceSpan from scenedetect.backends.concat import VideoStreamConcat as _VideoStreamConcat @@ -234,6 +237,9 @@ def __init__( # Enable frame threading for PyAV; other backends do not accept this option. kwargs = {"threading_mode": "AUTO"} if backend == "pyav" else {} super().__init__(paths, frame_rate=frame_rate, backend=backend, **kwargs) + # Coordinates `_offsets` and `_index` mutations in `read()`/`seek()`/`reset()` + # with cross-thread lookups in `locate()`. + self._offset_lock = threading.Lock() # WORKAROUND(scenedetect 0.7.2): the upstream constructor estimates where each input # starts on the global timeline from the child backend's declared duration, which # for PyAV is the frame count divided by the nominal rate. That is wrong for VFR @@ -242,9 +248,8 @@ def __init__( # Rebuild the estimates from the probed stream durations, which are time-based. # Depends on the private `_offsets` list; remove once upstream uses exact durations. offsets = [Fraction(0)] - for index, source in enumerate(self._source_info): - declared = source.duration if source.duration > 0 else self._sources[index].duration - offsets.append(offsets[-1] + declared) + for index in range(len(self._source_info)): + offsets.append(offsets[-1] + self.source_duration(index)) self._offsets = offsets @property @@ -252,6 +257,56 @@ def sources(self) -> ty.List[SourceInfo]: """Stream metadata for each input video.""" return self._source_info + def source_duration(self, index: int) -> Fraction: + """Declared duration of input `index` in seconds, falling back to the child + backend's duration if the container header reported 0.""" + probed = self._source_info[index].duration + return probed if probed > 0 else self._sources[index].duration + + def read(self, decode: bool = True): + """Read/decode the next frame, synchronizing source transitions with `locate`.""" + while True: + result = self._cap.read(decode=decode) + if result is not False: + return result + with self._offset_lock: + if (self._index + 1) >= len(self._paths): + logger.debug("No more input to process.") + return False + self._finish_current_source() + self._index += 1 + next_index = self._index + logger.debug("Processing complete, opening next video: %s", self._paths[next_index]) + self._cap = self._open_source(next_index) + + def seek(self, target): + with self._offset_lock: + super().seek(target) + + def reset(self): + with self._offset_lock: + super().reset() + + def locate(self, timecode: FrameTimecode) -> ty.Tuple[int, Fraction]: + """Find the input video that contains `timecode`, a time on the global timeline. + Returns the index of that video, and the time from its start in seconds. + + Thread-safe with `read()` for frames that have already been decoded: `read()` updates + `_offsets` and `_index` atomically under `_offset_lock`, and only the finalized prefix + `0.._index` (whose start offsets no longer change) is searched. + """ + # Timecodes from the scanner are rounded to 1 us, so the first frame of an input can + # be a little before its exact start time. Frames are much more than 1 us apart. + seconds = Fraction(timecode.pts) * timecode.time_base + with self._offset_lock: + limit = min(self._index, len(self._source_info) - 1) + index = ( + bisect.bisect_right(self._offsets, seconds + Fraction(1, 1000000), 0, limit + 1) - 1 + ) + index = max(0, min(index, limit)) + source_start = self._offsets[index] + return (index, max(Fraction(0), seconds - source_start)) + @property def resolution(self) -> ty.Tuple[int, int]: """Video resolution (width x height) in pixels. Alias for `frame_size`.""" diff --git a/dvr_scan/wallclock.py b/dvr_scan/wallclock.py new file mode 100644 index 0000000..7e76840 --- /dev/null +++ b/dvr_scan/wallclock.py @@ -0,0 +1,282 @@ +# +# DVR-Scan: Video Motion Event Detection & Extraction Tool +# -------------------------------------------------------------- +# [ Site: https://www.dvr-scan.com/ ] +# [ Repo: https://github.com/Breakthrough/DVR-Scan ] +# +# Copyright (C) 2016 Brandon Castellano . +# DVR-Scan is licensed under the BSD 2-Clause License; see the included +# LICENSE file, or visit one of the above pages for details. +# +"""``dvr_scan.wallclock`` Module + +Date and time of recording for the timecode overlay (the `time-code-start` option). + +The option gives the date and time of the first frame of each input video. The time of a +frame is that start time plus the presentation time of the frame in its video. Values: + + - `none`: no date and time. The overlay shows the position in the video. + - `filename`: read the start time from the file name (e.g. `20261116233730.avi` or + `VID_20261116_233730.mp4`). + - `modified`: the file modified time minus the duration of the video. Many cameras set + the modified time when a clip ends; cameras without a clock write a fixed date. + - a date and time (e.g. `2026-11-16 23:37:30`): the start time of the first input. If + all input file names contain a date and time, later inputs are placed using the + differences between their file name times (which corrects camera clock and time zone + errors and allows gaps between clips within one power cycle). Otherwise, later inputs + continue from the first input, as if the recording was continuous. + +All times are local times with no time zone, as cameras write them. +""" + +import logging +import re +import typing as ty +from datetime import datetime, timedelta +from fractions import Fraction +from pathlib import Path + +from scenedetect import FrameTimecode + +from dvr_scan.video_input import VideoStreamConcat + +logger = logging.getLogger("dvr_scan") + +NONE = "none" +FILENAME = "filename" +MODIFIED = "modified" +TIME_CODE_START_CHOICES = (NONE, FILENAME, MODIFIED) +"""Values of `time-code-start` other than a date and time.""" + +DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S" +"""Format of the date and time that the overlay shows.""" + +# A date and time in a file name: YYYYMMDDhhmmss, with consistent separators inside the +# date (YYYYMMDD or YYYYMMDD) and time (hhmmss or hhmmss) parts, e.g. +# 20261116233730, 20261116_233730, 2026-11-16_23-37-30, 2026-11-16t23:37:30. Requiring +# consistent separators prevents a 4-digit prefix or year from being split across fields, and +# the digit guards prevent matching inside a longer number. +_FILENAME_DATETIME = re.compile( + r"(?\d{4})(?P\d{2})(?P\d{2})" + r"|(?P\d{4})(?P[-_.])(?P\d{2})(?P=dsep)(?P\d{2}))" + r"[-_.Tt ]?" + r"(?:(?P

\d{2})(?P\d{2})(?P\d{2})" + r"|(?P

\d{2})(?P[-_.:])(?P\d{2})(?P=tsep)(?P\d{2}))" + r"(?!\d)" +) +# A year outside this range is more likely a counter than a date. +_MIN_YEAR = 1990 +_MAX_YEAR = 2100 + + +def parse_time_code_start(value: str) -> ty.Union[str, datetime]: + """Parse a `time-code-start` value. Returns one of `TIME_CODE_START_CHOICES`, or the + local date and time that the user gave. + + Raises: + ValueError: `value` is not a choice or a local date and time without a time zone. + """ + text = str(value).strip() + if text.lower() in TIME_CODE_START_CHOICES: + return text.lower() + try: + start = datetime.fromisoformat(text) + except ValueError: + raise ValueError( + f"Invalid time-code-start: {text}. Use one of: {', '.join(TIME_CODE_START_CHOICES)}," + " or a date and time as YYYY-MM-DD HH:MM:SS." + ) from None + if start.tzinfo is not None: + raise ValueError( + f"Invalid time-code-start: {text}. Give a local date and time without a time zone," + " e.g. YYYY-MM-DD HH:MM:SS." + ) + return start + + +def normalize_time_code_start(value: str) -> str: + """Validate and normalize a `time-code-start` value to a string (lowercasing keyword + choices).""" + parsed = parse_time_code_start(value) + return parsed if isinstance(parsed, str) else str(value).strip() + + +def start_time_from_filename(path: ty.Union[str, Path]) -> ty.Optional[datetime]: + """Date and time in the file name of `path`, or None if the name has none.""" + stem = Path(path).stem + pos = 0 + while (match := _FILENAME_DATETIME.search(stem, pos)) is not None: + year = int(match.group("y1") or match.group("y2")) + month = int(match.group("m1") or match.group("m2")) + day = int(match.group("d1") or match.group("d2")) + hour = int(match.group("H1") or match.group("H2")) + minute = int(match.group("M1") or match.group("M2")) + second = int(match.group("S1") or match.group("S2")) + if _MIN_YEAR <= year <= _MAX_YEAR: + try: + return datetime(year, month, day, hour, minute, second) + except ValueError: + pass + pos = match.start() + 1 + return None + + +def _modified_time(path: ty.Union[str, Path]) -> ty.Optional[datetime]: + """File modified time of `path` as local datetime, or None on error.""" + try: + return datetime.fromtimestamp(Path(path).stat().st_mtime) + except (OSError, OverflowError, ValueError) as ex: + logger.debug("Failed to get modified time of %s: %s", path, ex) + return None + + +def start_time_from_modified( + path: ty.Union[str, Path], duration: ty.Union[Fraction, float] +) -> ty.Optional[datetime]: + """File modified time of `path` minus `duration` (seconds), or None on error.""" + modified = _modified_time(path) + if modified is None: + return None + return modified - timedelta(seconds=float(duration)) + + +def _warn_missing(label: str, missing: ty.List[str], total: int) -> None: + if len(missing) == 1: + logger.warning( + "time-code-start: no %s date and time for %s. The timecode shows the" + " position in the video for this input.", + label, + missing[0], + ) + else: + logger.warning( + "time-code-start: no %s date and time for %d of %d inputs (e.g. %s). The" + " timecode shows the position in the video for those inputs.", + label, + len(missing), + total, + missing[0], + ) + + +class WallClock: + """Gives the date and time of recording for a time on the global timeline of a + `VideoStreamConcat`. Use `WallClock.create` to make one.""" + + def __init__(self, stream: VideoStreamConcat, mode: ty.Union[str, datetime]): + self._input = stream + # Start time of the first input, for continuous explicit-start mode. + self._start: ty.Optional[datetime] = None + # Start time of each input, for per-source modes. None if not known. + self._source_starts: ty.List[ty.Optional[datetime]] = [] + if isinstance(mode, datetime): + self._init_explicit(stream, mode) + return + if mode == FILENAME: + self._init_filename(stream) + return + assert mode == MODIFIED + self._init_modified(stream) + + def _init_explicit(self, stream: VideoStreamConcat, start: datetime) -> None: + if len(stream.sources) <= 1: + self._start = start + return + parsed = [ + name_time + for source in stream.sources + if (name_time := start_time_from_filename(source.path)) is not None + ] + if len(parsed) != len(stream.sources): + self._start = start + logger.warning( + "time-code-start: not all input file names have a date and time. Times for" + " later inputs assume that the recording was continuous." + ) + return + if any(curr < prev for prev, curr in zip(parsed, parsed[1:], strict=False)): + logger.warning( + "time-code-start: input file name times are not in order; timestamps still" + " use file name differences, which may be wrong if the camera clock reset" + " between files." + ) + offset = start - parsed[0] + for source, name_time in zip(stream.sources, parsed, strict=True): + source_start = name_time + offset + logger.debug("Start time of %s: %s", source.path.name, source_start) + self._source_starts.append(source_start) + + def _init_filename(self, stream: VideoStreamConcat) -> None: + missing: ty.List[str] = [] + for source in stream.sources: + start = start_time_from_filename(source.path) + if start is None: + missing.append(source.path.name) + else: + logger.debug("Start time of %s: %s", source.path.name, start) + self._source_starts.append(start) + if missing: + _warn_missing("file name", missing, len(stream.sources)) + + def _init_modified(self, stream: VideoStreamConcat) -> None: + missing: ty.List[str] = [] + zero_duration: ty.List[str] = [] + mtimes: ty.List[datetime] = [] + for index, source in enumerate(stream.sources): + modified = _modified_time(source.path) + if modified is None: + missing.append(source.path.name) + self._source_starts.append(None) + continue + mtimes.append(modified) + duration = stream.source_duration(index) + if duration <= 0: + zero_duration.append(source.path.name) + start = modified - timedelta(seconds=float(duration)) + logger.debug("Start time of %s: %s", source.path.name, start) + self._source_starts.append(start) + if missing: + _warn_missing("modified", missing, len(stream.sources)) + if zero_duration: + logger.warning( + "time-code-start: duration unknown for %d of %d inputs (e.g. %s); using" + " file modified time directly as start time.", + len(zero_duration), + len(stream.sources), + zero_duration[0], + ) + if len(mtimes) > 1 and len({m.replace(microsecond=0) for m in mtimes}) == 1: + logger.warning( + "time-code-start: all %d inputs have the same modified time (%s). Cameras" + " without a clock write a fixed date, so the timecode may not be accurate.", + len(mtimes), + mtimes[0].strftime(DATETIME_FORMAT), + ) + + @staticmethod + def create(stream: VideoStreamConcat, setting: str) -> ty.Optional["WallClock"]: + """Make a `WallClock` for the `time-code-start` value `setting`, or return None if + the value is `none`. + + Raises: + ValueError: `setting` is not a valid value. + """ + mode = parse_time_code_start(setting) + if mode == NONE: + return None + return WallClock(stream, mode) + + def get_text(self, timecode: FrameTimecode) -> ty.Optional[str]: + """Date and time of the frame at `timecode`, or None if not known. + + Safe to call from a thread other than the one that reads the input, for frames + that have been read already (see `VideoStreamConcat.locate`).""" + if self._start is not None: + when = self._start + timedelta(seconds=timecode.seconds) + return when.strftime(DATETIME_FORMAT) + index, local_seconds = self._input.locate(timecode) + start = self._source_starts[index] + if start is None: + return None + return (start + timedelta(seconds=float(local_seconds))).strftime(DATETIME_FORMAT) diff --git a/tests/test_application.py b/tests/test_application.py index eb9f061..4b27ecf 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -1022,3 +1022,67 @@ def test_event_table_destroy_cancels_loader_and_releases_video(tk_root, traffic_ assert not thread.is_alive() tk_root.after(100) assert _bgerrors(tk_root) == "" + + +def test_output_area_time_code_start_validation_and_default_scan_no_warning( + tk_root, traffic_camera_video, caplog +): + """OutputArea normalizes/validates time-code-start, never writes invalid values when + disabled, and default GUI settings do not trigger the CLI-only --time-code-start warning.""" + import logging + import tkinter as tk + + from dvr_scan.app.application import OutputArea + from dvr_scan.scanner import OutputMode + from dvr_scan.shared import init_scanner + + frame = tk.Frame(tk_root) + area = OutputArea(frame) + defaults = _scan_settings() + area.load(defaults) + + # Default GUI scan settings must not emit the CLI-only --time-code-start warning (#285). + saved = area.save(_scan_settings()) + saved.set("input", [traffic_camera_video]) + saved.set("output-mode", OutputMode.SCAN_ONLY) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + init_scanner(saved) + assert not any("--time-code-start has no effect" in r.message for r in caplog.records) + + # Keyword case normalization and blank -> "none". + area._timecode.set(True) + area._time_code_start.set(" FILENAME ") + assert area.validate_time_code_start() == "filename" + assert area._time_code_start.get() == "filename" + area._time_code_start.set(" ") + assert area.validate_time_code_start() == "none" + + # Invalid value raises while Timecode is enabled (blocks preset/config save and scan). + area._time_code_start.set("2026/11/16 23:37:30") + with pytest.raises(ValueError, match="Invalid time-code-start"): + area.validate_time_code_start() + + # When Timecode is unchecked (combobox disabled), save() preserves the last valid value + # so saving Default / presets cannot corrupt dvr-scan.cfg. + area._timecode.set(False) + assert area.validate_time_code_start() == "none" + saved_disabled = area.save(_scan_settings()) + assert saved_disabled.get("time-code-start") == "none" + + +def test_probe_video_uses_mtime_not_ctime(traffic_camera_video, tmp_path): + """The GUI Date column uses st_mtime rather than st_ctime (copy time on Windows, #285).""" + import os + import shutil + from datetime import datetime + + from dvr_scan.app.inputs import probe_video + + copied = tmp_path / "clip.mp4" + shutil.copyfile(traffic_camera_video, copied) + mtime = datetime(2024, 6, 15, 10, 20, 30) + os.utime(copied, (mtime.timestamp(), mtime.timestamp())) + info = probe_video(str(copied)) + assert info is not None + assert info.date == "2024-06-15 10:20:30" diff --git a/tests/test_cli.py b/tests/test_cli.py index f2ad61f..8fe5207 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -695,3 +695,29 @@ def test_save_region_writes_scanned_area(tmp_path, regions): assert saved == [[Point(631, 532), Point(841, 532), Point(841, 659), Point(631, 659)]] else: assert saved == [[Point(0, 0), Point(1279, 0), Point(1279, 719), Point(0, 719)]] + + +def test_cli_time_code_start_warning_and_validation(traffic_camera_video, caplog): + """--time-code-start warns when passed on the CLI without -tc (unless set to none), + and rejects invalid values.""" + from dvr_scan.shared import init_scanner + + settings = _parse_cli(["-i", traffic_camera_video, "-so", "--time-code-start", "FILENAME"]) + settings.set("input", [traffic_camera_video]) + assert settings.get("time-code-start") == "filename" + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + init_scanner(settings) + assert any("--time-code-start has no effect" in r.message for r in caplog.records) + + # Passing `--time-code-start none` without -tc must not warn. + settings_none = _parse_cli(["-i", traffic_camera_video, "-so", "--time-code-start", "none"]) + settings_none.set("input", [traffic_camera_video]) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + init_scanner(settings_none) + assert not any("--time-code-start has no effect" in r.message for r in caplog.records) + + # Invalid value fails CLI parsing. + with pytest.raises(SystemExit): + _parse_cli(["-i", traffic_camera_video, "--time-code-start", "not-a-date"]) diff --git a/tests/test_scan_context.py b/tests/test_scan_context.py index ca4a7dc..346684d 100644 --- a/tests/test_scan_context.py +++ b/tests/test_scan_context.py @@ -486,6 +486,41 @@ def test_start_duration(traffic_camera_video): compare_event_lists(event_list, TRAFFIC_CAMERA_EVENTS_AFTER_SEEK, AFTER_SEEK_FRAME_TOLERANCE) +@pytest.mark.parametrize( + "start_time,end_time,duration,message", + [ + # traffic_camera.mp4 is 23.04 seconds long. + ("01:00:00", None, None, "not before the end of the input"), + ("00:00:23.040", None, None, "not before the end of the input"), + ("00:00:05", "00:00:02", None, "not after start time"), + ("00:00:05", "00:00:05", None, "not after start time"), + (None, "00:00:00", None, "must be greater than 00:00:00.000"), + (None, None, 0, "must be greater than 00:00:00.000"), + ("00:00:05", None, 0, "not after start time"), + ], +) +def test_time_range_selects_no_frames( + traffic_camera_video, start_time, end_time, duration, message +): + """A start/end time or duration that selects no frames must raise an error, not scan + 0 frames (#285).""" + scanner = MotionScanner([traffic_camera_video]) + scanner.set_video_time(start_time=start_time, end_time=end_time, duration=duration) + with pytest.raises(ValueError, match=message): + scanner.scan() + + +def test_time_range_allows_unknown_duration_source(traffic_camera_video, monkeypatch): + """Streams whose container/backend report 0 duration must not fail the start-time check.""" + from fractions import Fraction + + scanner = MotionScanner([traffic_camera_video]) + monkeypatch.setattr(scanner._input, "source_duration", lambda _index: Fraction(0)) + scanner.set_video_time(start_time=0) + # _check_time_range must allow start_time=0 when duration is unknown. + scanner._check_time_range() + + def test_max_events(traffic_camera_video): """Setting max_events must end the scan as soon as that many events are found (#261).""" scanner = MotionScanner([traffic_camera_video]) diff --git a/tests/test_wallclock.py b/tests/test_wallclock.py new file mode 100644 index 0000000..9478d9a --- /dev/null +++ b/tests/test_wallclock.py @@ -0,0 +1,333 @@ +# +# DVR-Scan: Video Motion Event Detection & Extraction Tool +# -------------------------------------------------------------- +# [ Site: https://www.dvr-scan.com/ ] +# [ Repo: https://github.com/Breakthrough/DVR-Scan ] +# +# Copyright (C) 2016 Brandon Castellano . +# DVR-Scan is licensed under the BSD 2-Clause License; see the included +# LICENSE file, or visit one of the above pages for details. +# +"""DVR-Scan Wall Clock Tests + +Validates the date and time of recording for the timecode overlay (`time-code-start`, #285).""" + +import logging +import os +import shutil +from datetime import datetime +from fractions import Fraction +from pathlib import Path + +import pytest +from scenedetect import FrameTimecode + +from dvr_scan.cli import time_code_start_type +from dvr_scan.config import TimeCodeStartValue +from dvr_scan.overlays import TextOverlay +from dvr_scan.scanner import MotionScanner, OutputMode +from dvr_scan.video_input import open_input +from dvr_scan.wallclock import ( + WallClock, + normalize_time_code_start, + parse_time_code_start, + start_time_from_filename, + start_time_from_modified, +) + +# Duration of traffic_camera.mp4 in seconds (576 frames at 25 fps). +TRAFFIC_CAMERA_DURATION = 23.04 + + +@pytest.mark.parametrize( + "value,expected", + [ + ("none", "none"), + ("FileName", "filename"), + (" modified ", "modified"), + ("2026-11-16 23:37:30", datetime(2026, 11, 16, 23, 37, 30)), + ("2026-11-16T23:37:30", datetime(2026, 11, 16, 23, 37, 30)), + ], +) +def test_parse_time_code_start(value, expected): + assert parse_time_code_start(value) == expected + + +@pytest.mark.parametrize( + "value", + [ + "", + "yes", + "23:37:30", + "2026-13-01 00:00:00", + "2026-11-16T23:37:30Z", + "2026-11-16T23:37:30+02:00", + # Pre-1970 aware timestamp: must raise ValueError, not OSError on Windows. + "1960-01-01T00:00:00Z", + ], +) +def test_parse_time_code_start_invalid(value): + with pytest.raises(ValueError): + parse_time_code_start(value) + with pytest.raises(ValueError): + TimeCodeStartValue(value) + + +def test_normalize_time_code_start(): + assert normalize_time_code_start(" FILENAME ") == "filename" + assert TimeCodeStartValue(" MODIFIED ").value == "modified" + assert time_code_start_type(" None ") == "none" + assert TimeCodeStartValue(" 2026-11-16 23:37:30 ").value == "2026-11-16 23:37:30" + + +@pytest.mark.parametrize( + "name,expected", + [ + ("20261116233730.avi", datetime(2026, 11, 16, 23, 37, 30)), + ("VID_20261116_233730.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("2026-11-16t23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("REC20261116-233730_0001.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("cam1 2026.11.16 23.37.30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + # 4-digit prefixes and resolutions before the date must not swallow or corrupt it. + ("0001_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("CAM0001_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("1920x1080_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("1990_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("2001_1012_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + ("2026_13_01_2026-11-16_23-37-30.mp4", datetime(2026, 11, 16, 23, 37, 30)), + # No date and time in the name. + ("057706.avi", None), + ("traffic_camera.mp4", None), + # Not a valid date, or part of a longer number. + ("20261316233730.avi", None), + ("2026111623373099.avi", None), + ("00001116233730.avi", None), + ], +) +def test_start_time_from_filename(name, expected): + assert start_time_from_filename(Path("some_folder_20201010101010") / name) == expected + + +def test_start_time_from_modified(tmp_path): + path = tmp_path / "clip.avi" + path.write_bytes(b"") + modified = datetime(2026, 11, 16, 23, 38, 30) + os.utime(path, (modified.timestamp(), modified.timestamp())) + assert start_time_from_modified(path, 60) == datetime(2026, 11, 16, 23, 37, 30) + assert start_time_from_modified(tmp_path / "missing.avi", 60) is None + + +@pytest.fixture +def dated_inputs(traffic_camera_video, tmp_path) -> list[str]: + """Two copies of traffic_camera.mp4 with a start time in the file name.""" + paths = [tmp_path / "20261116233730.mp4", tmp_path / "VID_20261116_234500.mp4"] + for path in paths: + shutil.copyfile(traffic_camera_video, path) + return [str(path) for path in paths] + + +def _read_all(stream): + while stream.read(decode=False) is not False: + pass + + +def test_wall_clock_from_filename(dated_inputs): + """Each input uses the start time in its own file name.""" + stream = open_input(dated_inputs) + _read_all(stream) + clock = WallClock.create(stream, "filename") + get_text = clock.get_text + assert get_text(FrameTimecode(0.0, 25.0)) == "2026-11-16 23:37:30" + assert get_text(FrameTimecode(22.96, 25.0)) == "2026-11-16 23:37:52" + # First frame of the second input. The scanner rounds timecodes to 1 us. + assert get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION - 1e-7, 25.0)) == "2026-11-16 23:45:00" + assert get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION + 10.5, 25.0)) == "2026-11-16 23:45:10" + + +def test_wall_clock_locate_limited_to_current_input(dated_inputs): + """A time is not mapped to an input that the stream has not opened yet. The start time + of the next input is not final until the current input ends.""" + stream = open_input(dated_inputs) + assert stream.read() is not False + index, _ = stream.locate(FrameTimecode(TRAFFIC_CAMERA_DURATION + 1.0, 25.0)) + assert index == 0 + + +def test_wall_clock_explicit_start_anchors_dated_filenames(dated_inputs, caplog): + """When all inputs have dated file names, an explicit start time anchors the first input + and places later inputs using the differences between their file name times.""" + stream = open_input(dated_inputs) + _read_all(stream) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock = WallClock.create(stream, "2026-01-02 03:04:05") + assert not caplog.records + assert clock.get_text(FrameTimecode(0.0, 25.0)) == "2026-01-02 03:04:05" + # Second file name is 7m 30s after the first (23:37:30 -> 23:45:00). + assert clock.get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION, 25.0)) == "2026-01-02 03:11:35" + assert clock.get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION + 1, 25.0)) == "2026-01-02 03:11:36" + + +def test_wall_clock_explicit_start_out_of_order_warns(dated_inputs, caplog): + """Out-of-order dated file names still use file name differences, with one warning.""" + stream = open_input(list(reversed(dated_inputs))) + _read_all(stream) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock = WallClock.create(stream, "2026-01-02 03:11:35") + assert len(caplog.records) == 1 + assert "not in order" in caplog.records[0].message + assert clock.get_text(FrameTimecode(0.0, 25.0)) == "2026-01-02 03:11:35" + # Second file name is 7m 30s before the first (23:45:00 -> 23:37:30). + assert clock.get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION, 25.0)) == "2026-01-02 03:04:05" + + +def test_wall_clock_explicit_start_continuous_fallback(traffic_camera_video, tmp_path, caplog): + """If any input lacks a dated file name, an explicit start time falls back to continuous + recording with one warning.""" + paths = [tmp_path / "20261116233730.mp4", tmp_path / "clip02.mp4"] + for path in paths: + shutil.copyfile(traffic_camera_video, path) + stream = open_input([str(p) for p in paths]) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock = WallClock.create(stream, "2026-01-02 03:04:05") + assert len(caplog.records) == 1 + assert "continuous" in caplog.records[0].message + assert clock.get_text(FrameTimecode(0.0, 25.0)) == "2026-01-02 03:04:05" + assert clock.get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION + 1, 25.0)) == "2026-01-02 03:04:29" + + +def test_wall_clock_filename_missing_single_warning(traffic_camera_video, tmp_path, caplog): + """Multiple inputs with no file name timestamp produce one summary warning, not one per file.""" + paths = [tmp_path / "20261116233730.mp4", tmp_path / "clip01.mp4", tmp_path / "clip02.mp4"] + for path in paths: + shutil.copyfile(traffic_camera_video, path) + stream = open_input([str(p) for p in paths]) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + WallClock.create(stream, "filename") + assert len(caplog.records) == 1 + assert "2 of 3 inputs" in caplog.records[0].message + assert "clip01.mp4" in caplog.records[0].message + + +def test_wall_clock_modified_get_text_and_warnings( + traffic_camera_video, tmp_path, monkeypatch, caplog +): + """`modified` mode computes start = mtime - duration, warns once on identical mtimes + (even when truncated to whole seconds or another file fails stat), and warns on 0 duration.""" + paths = [tmp_path / "a.mp4", tmp_path / "b.mp4"] + fixed = datetime(2017, 5, 1, 1, 0, 0).timestamp() + for i, path in enumerate(paths): + shutil.copyfile(traffic_camera_video, path) + # Sub-second difference within the same second should still trigger identical-mtime warning. + os.utime(path, (fixed + 0.1 * i, fixed + 0.1 * i)) + stream = open_input([str(p) for p in paths]) + _read_all(stream) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock = WallClock.create(stream, "modified") + assert len(caplog.records) == 1 + assert "same modified time" in caplog.records[0].message + # 01:00:00 - 23.04s = 00:59:36.96 -> 00:59:36 + assert clock.get_text(FrameTimecode(0.0, 25.0)) == "2017-05-01 00:59:36" + + # Distinct modified times produce no warning and exact per-file wallclock times. + os.utime(paths[1], (fixed + 60, fixed + 60)) + stream2 = open_input([str(p) for p in paths]) + _read_all(stream2) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock2 = WallClock.create(stream2, "modified") + assert not caplog.records + assert clock2.get_text(FrameTimecode(TRAFFIC_CAMERA_DURATION, 25.0)) == "2017-05-01 01:00:36" + + # Zero duration warns and uses modified time directly. + monkeypatch.setattr(stream2, "source_duration", lambda _idx: Fraction(0)) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock3 = WallClock.create(stream2, "modified") + assert len(caplog.records) == 1 + assert "duration unknown" in caplog.records[0].message + assert clock3.get_text(FrameTimecode(0.0, 25.0)) == "2017-05-01 01:00:00" + + +def test_wall_clock_single_input_and_single_missing(traffic_camera_video, caplog): + """Single-input explicit start emits no warning; single missing filename emits one.""" + stream = open_input([traffic_camera_video]) + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock = WallClock.create(stream, "2026-01-02 03:04:05") + assert not caplog.records + assert clock.get_text(FrameTimecode(5.0, 25.0)) == "2026-01-02 03:04:10" + + caplog.clear() + with caplog.at_level(logging.WARNING, logger="dvr_scan"): + clock_fn = WallClock.create(stream, "filename") + assert len(caplog.records) == 1 + assert "traffic_camera.mp4" in caplog.records[0].message + assert clock_fn.get_text(FrameTimecode(1.0, 25.0)) is None + assert WallClock.create(stream, "none") is None + + +def test_locate_ignores_future_offsets_before_transition(dated_inputs): + """`locate` only searches finalized offsets 0.._index, so an overrun frame from source 0 + is never attributed to source 1 before source 0 finishes.""" + stream = open_input(dated_inputs) + # Simulate source 0 overrunning its declared end before transitioning to source 1. + assert stream._index == 0 + overrun_time = FrameTimecode(TRAFFIC_CAMERA_DURATION + 2.0, 25.0) + index, local = stream.locate(overrun_time) + assert index == 0 + assert float(local) == pytest.approx(TRAFFIC_CAMERA_DURATION + 2.0, abs=1e-4) + + +def test_scanner_draws_wall_clock_and_falls_back(traffic_camera_video, tmp_path, monkeypatch): + """MotionScanner passes wall-clock date/time text to TextOverlay.draw() when known, + and falls back to the video position when the filename has no timestamp.""" + dated = tmp_path / "20261116233730.mp4" + shutil.copyfile(traffic_camera_video, dated) + + drawn: list[str] = [] + orig_draw = TextOverlay.draw + + def record_draw(self, frame, text): + drawn.append(text) + return orig_draw(self, frame, text) + + monkeypatch.setattr(TextOverlay, "draw", record_draw) + + scanner = MotionScanner([str(dated)]) + scanner.set_output(output_mode=OutputMode.OPENCV, output_dir=tmp_path) + scanner.set_video_time(end_time="00:00:02") + scanner.set_event_params(min_event_len=1, time_pre_event=0, time_post_event=0) + scanner.set_detection_params(threshold=0.01) + scanner.set_overlays(timecode_overlay=TextOverlay(), time_code_start="filename") + scanner.scan() + assert drawn + assert all(text.startswith("2026-11-16 23:37:3") for text in drawn) + + # Undated filename falls back to elapsed HH:MM:SS.mmm video timecode. + drawn.clear() + scanner2 = MotionScanner([traffic_camera_video]) + scanner2.set_output(output_mode=OutputMode.OPENCV, output_dir=tmp_path) + scanner2.set_video_time(end_time="00:00:02") + scanner2.set_event_params(min_event_len=1, time_pre_event=0, time_post_event=0) + scanner2.set_detection_params(threshold=0.01) + scanner2.set_overlays(timecode_overlay=TextOverlay(), time_code_start="filename") + scanner2.scan() + assert drawn + assert all(text.startswith("00:00:0") for text in drawn) + + +def test_scanner_time_code_start(dated_inputs): + scanner = MotionScanner(dated_inputs) + with pytest.raises(ValueError): + scanner.set_overlays(timecode_overlay=TextOverlay(), time_code_start="bogus") + # The start time is not used without the timecode overlay. + scanner.set_overlays(time_code_start="filename") + assert scanner._wall_clock is None + scanner.set_overlays(timecode_overlay=TextOverlay(), time_code_start="filename") + assert scanner._wall_clock is not None