From 885e4525e610c1b3c95544065b24856048a81877 Mon Sep 17 00:00:00 2001
From: Isaac Connor <isaac@zoneminder.com>
Date: Tue, 28 Apr 2026 21:38:19 -0400
Subject: [PATCH 1/2] feat: optional WebVTT timestamp subtitle track in
 exported MP4s

Adds a new boolean config option ZM_OPT_EXPORT_TIMESTAMP_TRACK
(default off, category web). When enabled, the multi-event MP4
download path in web/includes/download_functions.php walks the
sorted event list, accumulates one WebVTT cue per second mapping
the concat-relative time to the source event's wall-clock
StartDateTime, writes timestamps.vtt next to event_files.txt, and
muxes it into the merged output as a mov_text subtitle stream
alongside the existing -c copy of video and audio. Also stamps an
MP4-level creation_time set to the earliest event start (UTC
ISO-8601). Off behavior is byte-identical to before: same
ffmpeg -f concat -safe 0 -i event_files.txt -c copy <out>.mp4.

Helpers formatVttTimestamp / buildVttContent / writeVttFile added
at the bottom of download_functions.php and unit-smoke-tested via
php -r. Falls back to (EndDateTime - StartDateTime) when an
event's Length is null/0; if neither is usable the cues for that
event are skipped with a debug log so the export still completes.

The subtitle stream is intended as a machine-readable record of
capture time per second, replacing the need to OCR the burned-in
OSD timestamp. mov_text is rendered by VLC and Safari and ignored
by browsers' <video> element without an explicit <track>; tools
can extract cues with `ffmpeg -map 0:s -f srt -` or read them via
`ffprobe -show_streams`.

refs #4761

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../lib/ZoneMinder/ConfigData.pm.in           | 17 ++++
 web/includes/download_functions.php           | 80 ++++++++++++++++++-
 2 files changed, 96 insertions(+), 1 deletion(-)

diff --git a/scripts/ZoneMinder/lib/ZoneMinder/ConfigData.pm.in b/scripts/ZoneMinder/lib/ZoneMinder/ConfigData.pm.in
index f7e7a64a86b..564cdd46162 100644
--- a/scripts/ZoneMinder/lib/ZoneMinder/ConfigData.pm.in
+++ b/scripts/ZoneMinder/lib/ZoneMinder/ConfigData.pm.in
@@ -1795,6 +1795,23 @@ our @options = (
     type        => $types{boolean},
     category    => 'web',
   },
+  {
+    name        => 'ZM_OPT_EXPORT_TIMESTAMP_TRACK',
+    default     => 'no',
+    description => 'Embed a per-second wall-clock timestamp subtitle track in exported MP4s',
+    help        => q`
+      When exporting (concatenating) events to an MP4 file, write a
+      WebVTT subtitle track containing one cue per second of footage,
+      where each cue text is the wall-clock date/time of that second
+      taken from the source event's StartDateTime. The track is muxed
+      into the output as a mov_text subtitle stream. This lets tools
+      recover the original capture time per frame without OCRing the
+      burned-in OSD timestamp. Players that ignore subtitle tracks
+      will play the file unchanged.
+      `,
+    type        => $types{boolean},
+    category    => 'web',
+  },
   {
     name        => 'ZM_WEB_POPUP_ON_ALARM',
     default     => 'yes',
diff --git a/web/includes/download_functions.php b/web/includes/download_functions.php
index d369a92a3fa..da7c422bad6 100644
--- a/web/includes/download_functions.php
+++ b/web/includes/download_functions.php
@@ -104,6 +104,8 @@ function downloadEvents(
     $minTime = '';
     $maxTimeSecs = -1;
     $maxTime = '';
+    $vttCues = [];
+    $concatOffset = 0.0;
     foreach ($events_by_monitor_id[$mid] as $event) {
       if ($minTimeSecs == -1 or $minTimeSecs > $event->StartDateTimeSecs()) {
         $minTimeSecs = $event->StartDateTimeSecs();
@@ -114,6 +116,32 @@ function downloadEvents(
         $maxTime = $event->EndDateTime();
       }
       $eventFileList .= 'file \''.$event->Path().'/'.$event->DefaultVideo().'\''.PHP_EOL;
+
+      $duration = (float)$event->Length();
+      if ($duration <= 0 and $event->EndDateTimeSecs()) {
+        $duration = $event->EndDateTimeSecs() - $event->StartDateTimeSecs();
+      }
+      if ($duration > 0) {
+        $eventStart = $event->StartDateTimeSecs();
+        $whole = (int)floor($duration);
+        for ($s = 0; $s < $whole; $s++) {
+          $vttCues[] = [
+            'start' => $concatOffset + $s,
+            'end'   => $concatOffset + $s + 1,
+            'text'  => date('Y-m-d H:i:s', $eventStart + $s),
+          ];
+        }
+        if ($duration - $whole > 0.001) {
+          $vttCues[] = [
+            'start' => $concatOffset + $whole,
+            'end'   => $concatOffset + $duration,
+            'text'  => date('Y-m-d H:i:s', $eventStart + $whole),
+          ];
+        }
+        $concatOffset += $duration;
+      } else {
+        ZM\Debug('Event '.$event->Id().' has no usable duration; skipping its timestamp cues');
+      }
     }
 
     $mergedFileName = $monitor->Name().' '.$minTime.' to '.$maxTime.'.mp4';
@@ -123,11 +151,35 @@ function downloadEvents(
     } else {
       ZM\Error("Can't open event images export file 'event_files.txt'");
     }
-    $cmd = ZM_PATH_FFMPEG.' -f concat -safe 0 -i event_files.txt -c copy '.escapeshellarg($export_dir.'/'.$mergedFileName). ' 2>&1';
+
+    $vttPath = '';
+    $useTimestampTrack = (defined('ZM_OPT_EXPORT_TIMESTAMP_TRACK') and ZM_OPT_EXPORT_TIMESTAMP_TRACK and !empty($vttCues));
+    if ($useTimestampTrack) {
+      $vttPath = 'timestamps.vtt';
+      if (writeVttFile($vttPath, $vttCues) === false) {
+        ZM\Error("Can't write timestamp track '$vttPath'; falling back to no-subtitle export");
+        $useTimestampTrack = false;
+      }
+    }
+
+    $cmd = ZM_PATH_FFMPEG.' -f concat -safe 0 -i event_files.txt';
+    if ($useTimestampTrack) {
+      $cmd .= ' -i '.escapeshellarg($vttPath)
+            .' -map 0:v -map 0:a? -map 1'
+            .' -c:v copy -c:a copy -c:s mov_text'
+            .' -metadata:s:s:0 language=eng -metadata:s:s:0 title=timestamp';
+      if ($minTimeSecs > 0) {
+        $cmd .= ' -metadata creation_time='.escapeshellarg(gmdate('Y-m-d\TH:i:s\Z', $minTimeSecs));
+      }
+    } else {
+      $cmd .= ' -c copy';
+    }
+    $cmd .= ' '.escapeshellarg($export_dir.'/'.$mergedFileName).' 2>&1';
     exec($cmd, $output, $return);
     ZM\Debug($cmd.' return code: '.$return.' output: '.print_r($output,true));
     $exportFileList[] = $mergedFileName;
     @unlink('event_files.txt');
+    if ($vttPath) @unlink($vttPath);
 
     # We're sending one file at a time to the archive. This will significantly save disk space.
     $command = '';
@@ -249,3 +301,29 @@ function getFlatCommandForTar() {
   }
   return $command;
 }
+
+function formatVttTimestamp($seconds) {
+  if ($seconds < 0) $seconds = 0;
+  $h = (int)floor($seconds / 3600);
+  $m = (int)floor(($seconds - $h * 3600) / 60);
+  $s = $seconds - $h * 3600 - $m * 60;
+  $whole = (int)floor($s);
+  $ms = (int)round(($s - $whole) * 1000);
+  if ($ms >= 1000) { $ms = 0; $whole += 1; }
+  return sprintf('%02d:%02d:%02d.%03d', $h, $m, $whole, $ms);
+}
+
+function buildVttContent($cues) {
+  $out = "WEBVTT\n\n";
+  foreach ($cues as $cue) {
+    if ($cue['end'] <= $cue['start']) continue;
+    $out .= formatVttTimestamp($cue['start']).' --> '.formatVttTimestamp($cue['end'])."\n";
+    $out .= $cue['text']."\n\n";
+  }
+  return $out;
+}
+
+function writeVttFile($path, $cues) {
+  $content = buildVttContent($cues);
+  return @file_put_contents($path, $content);
+}

From 0171f51898f96527a1c841f76975a9e2252fdca5 Mon Sep 17 00:00:00 2001
From: Isaac Connor <isaac@zoneminder.com>
Date: Tue, 28 Apr 2026 22:59:40 -0400
Subject: [PATCH 2/2] fix: carry overflow when formatting VTT cue timestamps

formatVttTimestamp() could emit invalid VTT timestamps such as
00:00:60.000 when the input second value (a float accumulated from
$concatOffset + $duration) was very close to a minute/hour boundary
and rounded ms up to 1000. The local +1 carry only handled seconds,
not minutes/hours.

Convert to integer milliseconds first and derive h/m/s/ms via
integer division/modulo so carry propagates correctly. Verified
59.9996 -> 00:01:00.000, 3599.9996 -> 01:00:00.000, negative
inputs clamp to zero.

refs #4761
---
 web/includes/download_functions.php | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/web/includes/download_functions.php b/web/includes/download_functions.php
index da7c422bad6..f7a6aa22621 100644
--- a/web/includes/download_functions.php
+++ b/web/includes/download_functions.php
@@ -303,14 +303,14 @@ function getFlatCommandForTar() {
 }
 
 function formatVttTimestamp($seconds) {
-  if ($seconds < 0) $seconds = 0;
-  $h = (int)floor($seconds / 3600);
-  $m = (int)floor(($seconds - $h * 3600) / 60);
-  $s = $seconds - $h * 3600 - $m * 60;
-  $whole = (int)floor($s);
-  $ms = (int)round(($s - $whole) * 1000);
-  if ($ms >= 1000) { $ms = 0; $whole += 1; }
-  return sprintf('%02d:%02d:%02d.%03d', $h, $m, $whole, $ms);
+  $totalMs = max(0, (int)round($seconds * 1000));
+  $h = (int)floor($totalMs / 3600000);
+  $remainder = $totalMs % 3600000;
+  $m = (int)floor($remainder / 60000);
+  $remainder = $remainder % 60000;
+  $s = (int)floor($remainder / 1000);
+  $ms = $remainder % 1000;
+  return sprintf('%02d:%02d:%02d.%03d', $h, $m, $s, $ms);
 }
 
 function buildVttContent($cues) {