Skip to content

feat: optional WebVTT timestamp subtitle track in exported MP4s #4766

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
connortechnology wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat: optional WebVTT timestamp subtitle track in exported MP4s #4766

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
885e452
feat: optional WebVTT timestamp subtitle track in exported MP4s
connortechnology Apr 29, 2026
0171f51
fix: carry overflow when formatting VTT cue timestamps
connortechnology Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions scripts/ZoneMinder/lib/ZoneMinder/ConfigData.pm.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
80 changes: 79 additions & 1 deletion web/includes/download_functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ function downloadEvents(
$minTime = '';
$maxTimeSecs = -1;
$maxTime = '';
$vttCues = [];
$concatOffset = 0.0;
Comment on lines +107 to +108
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When enabled, this builds an in-memory $vttCues array with one entry per second and then concatenates the entire WebVTT into a single string. For long exports, this can cause significant memory growth and slow string concatenation. A more scalable approach would be to stream cues directly to a file handle (write header once, then fwrite per cue) or generate/write cues per event rather than accumulating them all in arrays/strings.

Copilot uses AI. Check for mistakes.
foreach ($events_by_monitor_id[$mid] as $event) {
if ($minTimeSecs == -1 or $minTimeSecs > $event->StartDateTimeSecs()) {
$minTimeSecs = $event->StartDateTimeSecs();
Expand All @@ -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),
];
}
Comment on lines +127 to +133
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When enabled, this builds an in-memory $vttCues array with one entry per second and then concatenates the entire WebVTT into a single string. For long exports, this can cause significant memory growth and slow string concatenation. A more scalable approach would be to stream cues directly to a file handle (write header once, then fwrite per cue) or generate/write cues per event rather than accumulating them all in arrays/strings.

Copilot uses AI. Check for mistakes.
if ($duration - $whole > 0.001) {
$vttCues[] = [
'start' => $concatOffset + $whole,
'end' => $concatOffset + $duration,
'text' => date('Y-m-d H:i:s', $eventStart + $whole),
Comment on lines +131 to +138
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cue text timestamps are generated with date(...) (local timezone and no offset), while creation_time is written in UTC (gmdate(...)). This makes the exported timestamps ambiguous and potentially inconsistent across systems/timezone changes. Consider including an explicit timezone in cue text (e.g., UTC with gmdate or local with offset) so consumers can interpret timestamps unambiguously.

Suggested change
'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),
'text' => gmdate('Y-m-d H:i:s \U\T\C', $eventStart + $s),
];
}
if ($duration - $whole > 0.001) {
$vttCues[] = [
'start' => $concatOffset + $whole,
'end' => $concatOffset + $duration,
'text' => gmdate('Y-m-d H:i:s \U\T\C', $eventStart + $whole),

Copilot uses AI. Check for mistakes.
Comment on lines +131 to +138
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cue text timestamps are generated with date(...) (local timezone and no offset), while creation_time is written in UTC (gmdate(...)). This makes the exported timestamps ambiguous and potentially inconsistent across systems/timezone changes. Consider including an explicit timezone in cue text (e.g., UTC with gmdate or local with offset) so consumers can interpret timestamps unambiguously.

Suggested change
'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),
'text' => gmdate('Y-m-d H:i:s \U\T\C', $eventStart + $s),
];
}
if ($duration - $whole > 0.001) {
$vttCues[] = [
'start' => $concatOffset + $whole,
'end' => $concatOffset + $duration,
'text' => gmdate('Y-m-d H:i:s \U\T\C', $eventStart + $whole),

Copilot uses AI. Check for mistakes.
];
}
$concatOffset += $duration;
} else {
ZM\Debug('Event '.$event->Id().' has no usable duration; skipping its timestamp cues');
}
}

$mergedFileName = $monitor->Name().' '.$minTime.' to '.$maxTime.'.mp4';
Expand All @@ -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 = '';
Expand Down Expand Up @@ -249,3 +301,29 @@ function getFlatCommandForTar() {
}
return $command;
}

function formatVttTimestamp($seconds) {
$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) {
$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);
Comment on lines +316 to +328
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When enabled, this builds an in-memory $vttCues array with one entry per second and then concatenates the entire WebVTT into a single string. For long exports, this can cause significant memory growth and slow string concatenation. A more scalable approach would be to stream cues directly to a file handle (write header once, then fwrite per cue) or generate/write cues per event rather than accumulating them all in arrays/strings.

Suggested change
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);
function writeVttStream($stream, $cues) {
$bytesWritten = fwrite($stream, "WEBVTT\n\n");
if ($bytesWritten === false) {
return false;
}
foreach ($cues as $cue) {
if ($cue['end'] <= $cue['start']) continue;
$cueText = formatVttTimestamp($cue['start']).' --> '.formatVttTimestamp($cue['end'])."\n";
$cueText .= $cue['text']."\n\n";
$result = fwrite($stream, $cueText);
if ($result === false) {
return false;
}
$bytesWritten += $result;
}
return $bytesWritten;
}
function buildVttContent($cues) {
$stream = fopen('php://temp/maxmemory:1048576', 'w+b');
if ($stream === false) {
return false;
}
$result = writeVttStream($stream, $cues);
if ($result === false) {
fclose($stream);
return false;
}
rewind($stream);
$content = stream_get_contents($stream);
fclose($stream);
return $content;
}
function writeVttFile($path, $cues) {
$stream = @fopen($path, 'wb');
if ($stream === false) {
return false;
}
$result = writeVttStream($stream, $cues);
fclose($stream);
return $result;

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using the error suppression operator (@file_put_contents) can make failures harder to diagnose (it hides warnings like permission or disk-full issues). Prefer calling file_put_contents without @ and, on failure, logging the underlying error (e.g., via error_get_last()) so operations/debugging have actionable detail.

Suggested change
return @file_put_contents($path, $content);
$result = file_put_contents($path, $content);
if ($result === false) {
$lastError = error_get_last();
if ($lastError and isset($lastError['message'])) {
ZM\Error("Failed to write VTT file '$path': ".$lastError['message']);
} else {
ZM\Error("Failed to write VTT file '$path'");
}
}
return $result;

Copilot uses AI. Check for mistakes.
}
Loading