Add support for specifying the start time of the stream as part of th… (

#3988) * Add support for specifying the start time of the stream as part of the initialize or the attachSource call * Support for posix notation in attachSource and initialize call to define start time * Remove non required semicolon * Add missing JSDoc
Dash-Industry-Forum · Jul 15, 2022 · 54a45d7 · 54a45d7
1 parent 1f046c1
commit 54a45d7
Show file tree

Hide file tree

Showing 7 changed files with 278 additions and 124 deletions.
diff --git a/index.d.ts b/index.d.ts
@@ -364,7 +364,7 @@ declare namespace dashjs {
     export type TrackSelectionFunction = (tracks: MediaInfo[]) => MediaInfo[];
 
     export interface MediaPlayerClass {
-        initialize(view?: HTMLElement, source?: string, autoPlay?: boolean): void;
+        initialize(view?: HTMLElement, source?: string, autoPlay?: boolean, startTime?: number | string): void;
 
         on(type: AstInFutureEvent['type'], listener: (e: AstInFutureEvent) => void, scope?: object): void;
 
@@ -451,7 +451,7 @@ declare namespace dashjs {
 
         attachView(element: HTMLElement): void;
 
-        attachSource(urlOrManifest: string | object): void;
+        attachSource(urlOrManifest: string | object, startTime?: number | string): void;
 
         isReady(): boolean;
 

diff --git a/samples/advanced/load-with-starttime.html b/samples/advanced/load-with-starttime.html
@@ -0,0 +1,99 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Manual load with start time</title>
+
+    <script src="../../dist/dash.all.debug.js"></script>
+
+    <!-- Bootstrap core CSS -->
+    <link href="../lib/bootstrap/bootstrap.min.css" rel="stylesheet">
+    <link href="../lib/main.css" rel="stylesheet">
+
+    <style>
+        video {
+            width: 640px;
+            height: 360px;
+        }
+    </style>
+
+    <script class="code">
+        function init() {
+            var video,
+                player,
+                url = "https://livesim.dashif.org/livesim/testpic_2s/Manifest.mpd";
+
+            player = dashjs.MediaPlayer().create();
+            video = document.querySelector("video");
+            player.initialize(); /* initialize the MediaPlayer instance */
+
+            player.updateSettings({
+                debug: {
+                    logLevel: 4
+                }
+            });
+            const starttime = new Date().getTime() / 1000 - 60;
+            player.attachView(video); /* tell the player which videoElement it should use */
+            player.attachSource(url, `posix:${starttime}`); /* start from UTC time */
+            /* player.attachSource(url, starttime);  start relative to AST */
+        }
+    </script>
+</head>
+<body>
+
+<main>
+    <div class="container py-4">
+        <header class="pb-3 mb-4 border-bottom">
+            <img class=""
+                 src="../lib/img/dashjs-logo.png"
+                 width="200">
+        </header>
+        <div class="row">
+            <div class="col-md-4">
+                <div class="h-100 p-5 bg-light border rounded-3">
+                    <h3>Manual load with start time</h3>
+                    <p>A sample showing how to initialize playback at a specific start time.
+                    <ul>
+                        <li>For VoD content the start time is relative to the start time of the first period.</li>
+                        <li>For live content
+                            <ul>
+                                <li>If the parameter starts from prefix
+                                    posix: it signifies the absolute time range defined in seconds of Coordinated
+                                    Universal Time
+                                    (ITU-R TF.460-6). This is the number of seconds since 01-01-1970 00:00:00 UTC.
+                                    Fractions of
+                                    seconds may be optionally specified down to the millisecond level.
+                                </li>
+                                <li>If no posix prefix is used the starttime is relative to MPD@availabilityStartTime</li>
+                            </ul>
+                        </li>
+                    </ul>
+                    </p>
+                    <p>In this example playback starts 60 seconds from the current wall clock time.
+                    </p>
+                </div>
+            </div>
+            <div class="col-md-8">
+                <video controls="true"></video>
+            </div>
+        </div>
+        <div class="row">
+            <div class="col-md-12">
+                <div id="code-output"></div>
+            </div>
+        </div>
+        <footer class="pt-3 mt-4 text-muted border-top">
+            &copy; DASH-IF
+        </footer>
+    </div>
+</main>
+
+
+<script>
+    document.addEventListener('DOMContentLoaded', function () {
+        init();
+    });
+</script>
+<script src="../highlighter.js"></script>
+</body>
+</html>
diff --git a/samples/samples.json b/samples/samples.json
@@ -670,6 +670,17 @@
                     "Video",
                     "Audio"
                 ]
+            },
+            {
+                "title": "Manual load with start time",
+                "description": "A sample showing how to initialize playback at a specific start time.",
+                "href": "advanced/load-with-starttime.html",
+                "image": "lib/img/bbb-4.jpg",
+                "labels": [
+                    "VoD",
+                    "Video",
+                    "Audio"
+                ]
             }
         ]
     },

diff --git a/src/streaming/MediaPlayer.js b/src/streaming/MediaPlayer.js
@@ -252,14 +252,17 @@ function MediaPlayer() {
      *
      * @param {HTML5MediaElement=} view - Optional arg to set the video element. {@link module:MediaPlayer#attachView attachView()}
      * @param {string=} source - Optional arg to set the media source. {@link module:MediaPlayer#attachSource attachSource()}
-     * @param {boolean=} AutoPlay - Optional arg to set auto play. {@link module:MediaPlayer#setAutoPlay setAutoPlay()}
-     * @see {@link module:MediaPlayer#attachView attachView()}
+     * @param {boolean=} autoPlay - Optional arg to set auto play. {@link module:MediaPlayer#setAutoPlay setAutoPlay()}
+     * @param {number|string} startTime - For VoD content the start time is relative to the start time of the first period.
+     * For live content
+     * If the parameter starts from prefix posix: it signifies the absolute time range defined in seconds of Coordinated Universal Time (ITU-R TF.460-6). This is the number of seconds since 01-01-1970 00:00:00 UTC. Fractions of seconds may be optionally specified down to the millisecond level.
+     * If no posix prefix is used the starttime is relative to MPD@availabilityStartTime
      * @see {@link module:MediaPlayer#attachSource attachSource()}
      * @see {@link module:MediaPlayer#setAutoPlay setAutoPlay()}
      * @memberof module:MediaPlayer
      * @instance
      */
-    function initialize(view, source, AutoPlay) {
+    function initialize(view, source, autoPlay, startTime = NaN) {
         if (!capabilities) {
             capabilities = Capabilities(context).getInstance();
             capabilities.setConfig({
@@ -381,7 +384,7 @@ function MediaPlayer() {
             });
 
             restoreDefaultUTCTimingSources();
-            setAutoPlay(AutoPlay !== undefined ? AutoPlay : true);
+            setAutoPlay(autoPlay !== undefined ? autoPlay : true);
 
             // Detect and initialize offline module to support offline contents playback
             _detectOffline();
@@ -392,7 +395,7 @@ function MediaPlayer() {
         }
 
         if (source) {
-            attachSource(source);
+            attachSource(source, startTime);
         }
 
         logger.info('[dash.js ' + getVersion() + '] ' + 'MediaPlayer has been initialized');
@@ -1790,14 +1793,17 @@ function MediaPlayer() {
      *
      * @param {string|Object} urlOrManifest - A URL to a valid MPD manifest file, or a
      * parsed manifest object.
-     *
+     * @param {number|string} startTime - For VoD content the start time is relative to the start time of the first period.
+     * For live content
+     * If the parameter starts from prefix posix: it signifies the absolute time range defined in seconds of Coordinated Universal Time (ITU-R TF.460-6). This is the number of seconds since 01-01-1970 00:00:00 UTC. Fractions of seconds may be optionally specified down to the millisecond level.
+     * If no posix prefix is used the starttime is relative to MPD@availabilityStartTime
      *
      * @throws {@link module:MediaPlayer~MEDIA_PLAYER_NOT_INITIALIZED_ERROR MEDIA_PLAYER_NOT_INITIALIZED_ERROR} if called before initialize function
      *
      * @memberof module:MediaPlayer
      * @instance
      */
-    function attachSource(urlOrManifest) {
+    function attachSource(urlOrManifest, startTime = NaN) {
         if (!mediaPlayerInitialized) {
             throw MEDIA_PLAYER_NOT_INITIALIZED_ERROR;
         }
@@ -1813,7 +1819,7 @@ function MediaPlayer() {
         }
 
         if (isReady()) {
-            _initializePlayback();
+            _initializePlayback(startTime);
         }
     }
 
@@ -2262,7 +2268,11 @@ function MediaPlayer() {
         return utcValue;
     }
 
-    function _initializePlayback() {
+    /**
+     *
+     * @private
+     */
+    function _initializePlayback(startTime = NaN) {
 
         if (offlineController) {
             offlineController.resetRecords();
@@ -2274,9 +2284,9 @@ function MediaPlayer() {
             _createPlaybackControllers();
 
             if (typeof source === 'string') {
-                streamController.load(source);
+                streamController.load(source, startTime);
             } else {
-                streamController.loadWithManifest(source);
+                streamController.loadWithManifest(source, startTime);
             }
         }