Dash-Industry-Forum · malthejorgensen · Mar 13, 2021 · Mar 13, 2021 · Mar 16, 2021 · Mar 16, 2021
diff --git a/index.d.ts b/index.d.ts
@@ -339,6 +339,7 @@ declare namespace dashjs {
         setQualityFor(type: MediaType, value: number): void;
         updatePortalSize(): void;
         enableText(enable: boolean): void;
+        addTextTrack(url: string, mediaInfo: MediaInfo): void;
         setTextTrack(idx: number): void;
         getTextDefaultLanguage(): string | undefined;
         setTextDefaultLanguage(lang: string): void;

diff --git a/samples/captioning/external-caption-vtt.html b/samples/captioning/external-caption-vtt.html
@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8"/>
+    <title>WebVTT Dash Demo</title>
+    <meta name="description" content="" />
+    <link rel="icon" type="image/x-icon" href="http://dashif.org/wp-content/uploads/2014/12/dashif.ico" />
+
+    <script src="../../dist/dash.all.debug.js"></script>
+    <!--dash.all.min.js should be used in production over dash.all.debug.js
+        Debug files are not compressed or obfuscated making the file size much larger compared with dash.all.min.js-->
+    <!--<script src="../../dist/dash.all.min.js"></script>-->
+
+    <script class="code">
+        function startVideo() {
+            var url = "https://dash.akamaized.net/akamai/test/caption_test/ElephantsDream/elephants_dream_480p_heaac5_1.mpd",
+                video = document.querySelector(".dash-video-player video"),
+                player;
+
+            player = dashjs.MediaPlayer({}).create();
+            player.initialize(video, url, true);
+            player.setTextDefaultEnabled(true);
+
+            var mediaInfo = {
+                id: 1,
+                lang: 'en-US',
+                index: null,
+                type: null,
+                streamInfo: null,
+                representationCount: 0,
+                viewpoint: null,
+                roles: [],
+                codec: null,
+                mimeType: null,
+                contentProtection: null,
+                isText: true,
+                KID: null,
+                bitrateList: null,
+            }
+
+            player.on(dashjs.MediaPlayer.events['STREAM_INITIALIZED'], function handleEvent(e) {
+                // Relative URL used here -- absolute URLs are also supported
+                player.addTextTrack('external-captions.vtt', mediaInfo);
+            });
+        }
+    </script>
+
+    <style>
+        video {
+            width: 640px;
+            height: 360px;
+        }
+    </style>
+
+    <body onload="startVideo()">
+        <div class="dash-video-player">
+            <video controls="true"></video>
+        </div>
+    </body>
+    <script src="../highlighter.js"></script>
+</html>
diff --git a/samples/captioning/external-captions.vtt b/samples/captioning/external-captions.vtt
@@ -0,0 +1,10 @@
+WEBVTT
+
+00:00:00.500 --> 00:00:04.000
+These are example captions in the VTT format
+
+00:00:04.500 --> 00:00:08.300
+They are not listed in the manifest file
+
+00:00:010.000 --> 00:00:14.000
+This is the last caption. Enjoy!
diff --git a/samples/samples.json b/samples/samples.json
@@ -154,6 +154,11 @@
                 "title": "TTML EBU timed text tracks",
                 "description": "Example showing content with TTML EBU timed text tracks.",
                 "href": "captioning/ttml-ebutt-sample.html"
+            },
+            {
+                "title": "Load external VTT captions",
+                "description": "Example showing how to load external VTT captions.",
+                "href": "captioning/external-caption-vtt.html"
             }
         ]
     },

diff --git a/src/core/errors/Errors.js b/src/core/errors/Errors.js
@@ -112,6 +112,9 @@ class Errors extends ErrorsBase {
         this.REMOVE_ERROR_MESSAGE = 'buffer is not defined';
         this.DATA_UPDATE_FAILED_ERROR_MESSAGE = 'Data update failed';
 
+        this.CAPTIONS_LOADER_PARSING_FAILURE_ERROR_MESSAGE = 'caption parsing failed for ';
+        this.CAPTIONS_LOADER_LOADING_FAILURE_ERROR_MESSAGE = 'Failed loading captions: ';
+
         this.CAPABILITY_MEDIASOURCE_ERROR_MESSAGE = 'mediasource is not supported';
         this.CAPABILITY_MEDIAKEYS_ERROR_MESSAGE = 'mediakeys is not supported';
         this.TIMED_TEXT_ERROR_MESSAGE_PARSE = 'parsing error :';

diff --git a/src/core/events/CoreEvents.js b/src/core/events/CoreEvents.js
@@ -64,6 +64,7 @@ class CoreEvents extends EventsBase {
         this.MANIFEST_UPDATED = 'manifestUpdated';
         this.MEDIA_FRAGMENT_LOADED = 'mediaFragmentLoaded';
         this.MEDIA_FRAGMENT_NEEDED = 'mediaFragmentNeeded';
+        this.EXTERNAL_CAPTIONS_LOADED = 'externalCaptionsLoaded';
         this.QUOTA_EXCEEDED = 'quotaExceeded';
         this.REPRESENTATION_UPDATE_STARTED = 'representationUpdateStarted';
         this.REPRESENTATION_UPDATE_COMPLETED = 'representationUpdateCompleted';

diff --git a/src/streaming/CaptionsLoader.js b/src/streaming/CaptionsLoader.js
@@ -0,0 +1,183 @@
+/**
+ * The copyright in this software is being made available under the BSD License,
+ * included below. This software may be subject to other third party and contributor
+ * rights, including patent rights, and no such rights are granted under this license.
+ *
+ * Copyright (c) 2013, Dash Industry Forum.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *  * Redistributions of source code must retain the above copyright notice, this
+ *  list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright notice,
+ *  this list of conditions and the following disclaimer in the documentation and/or
+ *  other materials provided with the distribution.
+ *  * Neither the name of Dash Industry Forum nor the names of its
+ *  contributors may be used to endorse or promote products derived from this software
+ *  without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY
+ *  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ *  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+import Constants from './constants/Constants';
+import DashConstants from '../dash/constants/DashConstants';
+import URLLoader from './net/URLLoader';
+import URLUtils from './utils/URLUtils';
+import TextRequest from './vo/TextRequest';
+import DashJSError from './vo/DashJSError';
+import {HTTPRequest} from './vo/metrics/HTTPRequest';
+import EventBus from '../core/EventBus';
+import Events from '../core/events/Events';
+import Errors from '../core/errors/Errors';
+import FactoryMaker from '../core/FactoryMaker';
+import VTTParser from './utils/VTTParser';
+
+function CaptionsLoader(config) {
+
+    config = config || {};
+    const context = this.context;
+    const debug = config.debug;
+    const eventBus = EventBus(context).getInstance();
+    const urlUtils = URLUtils(context).getInstance();
+
+    let instance,
+        logger,
+        urlLoader,
+        parser;
+
+    let mssHandler = config.mssHandler;
+    let errHandler = config.errHandler;
+
+    function setup() {
+        logger = debug.getLogger(instance);
+
+        urlLoader = URLLoader(context).create({
+            errHandler: config.errHandler,
+            dashMetrics: config.dashMetrics,
+            mediaPlayerModel: config.mediaPlayerModel,
+            requestModifier: config.requestModifier,
+            useFetch: config.settings.get().streaming.lowLatencyEnabled,
+            urlUtils: urlUtils,
+            constants: Constants,
+            dashConstants: DashConstants,
+            errors: Errors
+        });
+    }
+
+    function createParser(data) {
+        if (data.indexOf('WEBVTT') > -1) {
+            return VTTParser(context).getInstance();
+        }
+        // } else if (data.indexOf('MPD') > -1 || data.indexOf('Patch') > -1) {
+        //     return DashParser(context).create({debug: debug});
+        // } else {
+        //     return parser;
+        // }
+        return null;
+    }
+
+    function load(url) {
+
+        const request = new TextRequest(url, HTTPRequest.MEDIA_SEGMENT_TYPE);
+
+        urlLoader.load({
+            request: request,
+            success: function (data, textStatus, responseURL) {
+                let actualUrl,
+                    captions;
+
+                // Handle redirects for the MPD - as per RFC3986 Section 5.1.3
+                // also handily resolves relative MPD URLs to absolute
+                if (responseURL && responseURL !== url) {
+                    actualUrl = responseURL;
+                } else {
+                    // usually this case will be caught and resolved by
+                    // responseURL above but it is not available for IE11 and Edge/12 and Edge/13
+                    if (urlUtils.isRelative(url)) {
+                        url = urlUtils.resolve(url, window.location.href);
+                    }
+                }
+
+                // A response of no content implies in-memory is properly up to date
+                if (textStatus == 'No Content') {
+                    return;
+                }
+
+                // Create parser according to captions type
+                parser = createParser(data);
+
+                if (parser === null) {
+                    eventBus.trigger(Events.EXTERNAL_CAPTIONS_LOADED, {
+                        captions: null,
+                        error: new DashJSError(
+                            Errors.CAPTIONS_LOADER_PARSING_FAILURE_ERROR_CODE,
+                            Errors.CAPTIONS_LOADER_PARSING_FAILURE_ERROR_MESSAGE + `${url}`
+                        )
+                    });
+                    return;
+                }
+
+                try {
+                    captions = parser.parse(data, 0);
+                } catch (e) {
+                    errHandler.error(new DashJSError(Errors.TIMED_TEXT_ERROR_ID_PARSE_CODE, Errors.TIMED_TEXT_ERROR_MESSAGE_PARSE + e.message, data));
+                }
+
+                if (captions) {
+                    eventBus.trigger(Events.EXTERNAL_CAPTIONS_LOADED, { captions: captions });
+                } else {
+                    eventBus.trigger(Events.EXTERNAL_CAPTIONS_LOADED, {
+                        captions: null,
+                        error: new DashJSError(
+                            Errors.CAPTIONS_LOADER_PARSING_FAILURE_ERROR_CODE,
+                            Errors.CAPTIONS_LOADER_PARSING_FAILURE_ERROR_MESSAGE + `${url}`
+                        )
+                    });
+                }
+            },
+            error: function (request, statusText, errorText) {
+                eventBus.trigger(Events.EXTERNAL_CAPTIONS_LOADED, {
+                    captions: null,
+                    error: new DashJSError(
+                        Errors.CAPTIONS_LOADER_LOADING_FAILURE_ERROR_CODE,
+                        Errors.CAPTIONS_LOADER_LOADING_FAILURE_ERROR_MESSAGE + `${url}, ${errorText}`
+                    )
+                });
+            }
+        });
+    }
+
+    function reset() {
+        if (urlLoader) {
+            urlLoader.abort();
+            urlLoader = null;
+        }
+
+        if (mssHandler) {
+            mssHandler.reset();
+        }
+    }
+
+    instance = {
+        load: load,
+        reset: reset
+    };
+
+    setup();
+
+    return instance;
+}
+
+CaptionsLoader.__dashjs_factory_name = 'CaptionsLoader';
+
+const factory = FactoryMaker.getClassFactory(CaptionsLoader);
+export default factory;