From dde93065dfa6b65f31645ece4a376432e1f0b38c Mon Sep 17 00:00:00 2001
From: bp2008 <bp2008@users.noreply.github.com>
Date: Sat, 29 Jul 2023 10:52:06 -0600
Subject: [PATCH] Version 251: * The "timeline=" URL parameter can now accept a
 negative number of milliseconds to offset from "live". * The "timeline=" URL
 parameter can now accept a date string in any format parseable by JavaScript,
 to make it easier for users to do manual entry or interoprate with other
 applications. * Added "pause=1" URL parameter to allow clip or timeline video
 to start in the paused state.  It is currently not possible to start live
 video paused.

---
 ui3.htm            |  2 +-
 ui3/help/help.html | 20 +++++++++++++++++---
 ui3/ui3.js         | 37 +++++++++++++++++++++++++++++++++----
 3 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/ui3.htm b/ui3.htm
index 018b266..662ad52 100644
--- a/ui3.htm
+++ b/ui3.htm
@@ -88,7 +88,7 @@
 		};
 	</script>
 	<script type="text/javascript">
-		var ui_version = "250";
+		var ui_version = "251";
 		var bi_version = "%%VERSION%%";
 		var appPath_raw = "%%VIRTDIR%%";
 		var local_bi_session = "%%SESSION%%";
diff --git a/ui3/help/help.html b/ui3/help/help.html
index 19abefa..0ce580f 100644
--- a/ui3/help/help.html
+++ b/ui3/help/help.html
@@ -437,10 +437,15 @@ <h1>URL Parameters</h1>
 									<td><a href="../../ui3.htm?rec=21148130039-10000" target="_blank">ui3.htm?rec=21148130039-10000</a></td>
 								</tr>
 								<tr>
-									<td>timeline=MS<br /><span class="urlParameterAlias" title="This shorter alternative can be used instead">tl=</span></td>
+									<td>timeline=DATE<br /><span class="urlParameterAlias" title="This shorter alternative can be used instead">tl=</span></td>
 									<td>
 										<p>
-											Opens the timeline tab and seeks to the specified millisecond position. The "MS" value should be a JavaScript timestamp (number of milliseconds since the unix epoch, ignoring leap seconds).
+											Opens the timeline tab and seeks to the specified date and time. The "DATE" value can be:
+											<ul>
+												<li>A JavaScript timestamp (number of milliseconds since the unix epoch, ignoring leap seconds).</li>
+												<li>A negative number of milliseconds to offset from the current time (e.g. (<code>-30000</code> to start 30 seconds back from "live").</li>
+												<li>A date and time string that is parseable by JavaScript's <code>Date.parse()</code> function (e.g. <code>2023-07-29.18:14:00</code>). Be sure to properly <a href="https://www.google.com/search?q=url+encoding" target="_blank">URL-encode</a> your string if you have difficulty using this.</li>
+											</ul>
 										</p>
 										<p style="font-style: italic;">
 											To make it easy to share links, this parameter is automatically entered into the address bar during timeline playback.
@@ -448,11 +453,20 @@ <h1>URL Parameters</h1>
 									</td>
 									<td><a href="../../ui3.htm?timeline=" target="_blank" id="timelineLink">ui3.htm?timeline=</a></td>
 								</tr>
+								<tr>
+									<td>pause=1</td>
+									<td>
+										<p>
+											The specified clip or timeline position will start paused.  Live video currently can't be started paused.
+										</p>
+									</td>
+									<td><a href="../../ui3.htm?timeline=-30000&pause=1" target="_blank">ui3.htm?timeline=-30000&pause=1</a></td>
+								</tr>
 								<tr>
 									<td>streamingprofile=name<br /><span class="urlParameterAlias" title="This shorter alternative can be used instead">p=</span></td>
 									<td>
 										<p>
-											Selects a specific streaming profile at UI3 startup.  The value <code>name</code> must exactly match one of your streaming profiles.  Streaming profile names are case-sensitive and should be URL-encoded when used in a URL parameter.
+											Selects a specific streaming profile at UI3 startup.  The value <code>name</code> must exactly match one of your streaming profiles.  Streaming profile names are case-sensitive and should be <a href="https://www.google.com/search?q=url+encoding" target="_blank">URL-encoded</a> when used in a URL parameter.
 										</p>
 										<p id="streamingProfileListParagraph" style="display: none;">
 											This is a list of your streaming profiles which you may copy from:
diff --git a/ui3/ui3.js b/ui3/ui3.js
index 83b22f6..a3883bb 100644
--- a/ui3/ui3.js
+++ b/ui3/ui3.js
@@ -3627,6 +3627,7 @@ function ReloadInterface()
 var skipLoadingFirstVideoStream = false;
 var skipLoadingAllVideoStreams = false;
 var startupTimelineMs = null;
+var startupPaused = false;
 var startupClipFilterSearch = null;
 var startupClipFilterBeginDate = null;
 var startupClipFilterEndDate = null;
@@ -3719,11 +3720,13 @@ function HandlePreLoadUrlParameters()
 	}
 
 	// Parameter "timeline", value is a millisecond timestamp
-	var timelineMs = UrlParameters.Get("timeline", "tl");
-	if (timelineMs !== '')
+	var timelineMsStr = UrlParameters.Get("timeline", "tl");
+	if (timelineMsStr !== '')
 	{
-		timelineMs = parseInt(timelineMs);
-		if (!isNaN(timelineMs) && timelineMs > 0)
+		var timelineMs = parseInt(timelineMsStr);
+		if (isNaN(timelineMs) || (timelineMs > 0 && timelineMs < 60000))
+			timelineMs = Date.parse(timelineMsStr.replace('_', ' '));
+		if (!isNaN(timelineMs))
 		{
 			settings.ui3_defaultTab = "timeline";
 			skipLoadingAllVideoStreams = true;
@@ -3754,6 +3757,11 @@ function HandlePreLoadUrlParameters()
 		else
 			console.log('"timeout"/"to" URL parameter received invalid value: ' + timeoutParam);
 	}
+
+	// Parameter "pause"
+	var pauseParam = UrlParameters.Get("pause");
+	if (pauseParam === "1" || maximize.toLowerCase() === "true")
+		startupPaused = true;
 }
 function StartupClipOpener(recId, offset)
 {
@@ -7166,6 +7174,8 @@ function ClipTimeline()
 				loadingHelper.SetLoadedStatus("timeline");
 				if (startupTimelineMs !== null)
 				{
+					if (startupTimelineMs < 0)
+						startupTimelineMs = GetUtcNow() + startupTimelineMs;
 					skipLoadingAllVideoStreams = false;
 					developerLog("Timeline component created. Starting playback at " + startupTimelineMs);
 					this.assignLastSetTime(startupTimelineMs);
@@ -16478,6 +16488,13 @@ function JpegVideoModule()
 			offsetPercent = 0;
 		if (loading.isLive)
 			startPaused = false;
+		if (!loading.isLive && startupPaused)
+		{
+			// We don't allow live video to start paused due to a long-standing bugs where the live video will just render black if we do.
+			console.log("Starting video paused");
+			startPaused = true;
+		}
+		startupPaused = false;
 		Activate();
 		if (playbackControls.GetPlayReverse() && offsetPercent === 0)
 			offsetPercent = 1;
@@ -17043,6 +17060,13 @@ function FetchH264VideoModule()
 			offsetPercent = 0;
 		if (loading.isLive)
 			startPaused = false;
+		if (!loading.isLive && startupPaused)
+		{
+			// We don't allow live video to start paused due to a long-standing bugs where the live video will just render black if we do.
+			console.log("Starting video paused");
+			startPaused = true;
+		}
+		startupPaused = false;
 		Activate();
 		lastStatusBlock = null;
 		if (playbackControls.GetPlayReverse() && offsetPercent === 0)
@@ -27921,6 +27945,7 @@ function GetCleanUrlSearchParams()
 	search.delete("p");
 	search.delete("timeout");
 	search.delete("to");
+	search.delete("pause");
 	return search;
 }
 function UpdateCurrentURL()
@@ -27936,6 +27961,8 @@ function UpdateCurrentURL()
 	{
 		search.set("timeline", clipTimeline.getCurrentTime());
 		search.delete("t");
+		if (videoPlayer.Playback_IsPaused())
+			search.set("pause", "1");
 	}
 	else if (!cli.isLive)
 	{
@@ -27948,6 +27975,8 @@ function UpdateCurrentURL()
 				val += "-" + offset;
 			search.set("rec", val);
 			search.delete("t");
+			if (videoPlayer.Playback_IsPaused())
+				search.set("pause", "1");
 		}
 	}