Source: lib/text/text_engine.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.text.TextEngine');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.util.Error');
  22. goog.require('shaka.util.IDestroyable');
  26. /**
  27.  * Manages text parsers and cues.
  28.  *
  29.  * @param {shakaExtern.TextDisplayer} displayer
  30.  * @struct
  31.  * @constructor
  32.  * @implements {shaka.util.IDestroyable}
  33.  */
  34. shaka.text.TextEngine = function(displayer) {
  35.   /** @private {shakaExtern.TextParser} */
  36.   this.parser_ = null;
  38.   /** @private {shakaExtern.TextDisplayer} */
  39.   this.displayer_ = displayer;
  41.   /** @private {number} */
  42.   this.timestampOffset_ = 0;
  44.   /** @private {number} */
  45.   this.appendWindowStart_ = 0;
  47.   /** @private {number} */
  48.   this.appendWindowEnd_ = Infinity;
  50.   /** @private {?number} */
  51.   this.bufferStart_ = null;
  53.   /** @private {?number} */
  54.   this.bufferEnd_ = null;
  55. };
  58. /** @private {!Object.<string, !shakaExtern.TextParserPlugin>} */
  59. shaka.text.TextEngine.parserMap_ = {};
  62. /**
  63.  * @param {string} mimeType
  64.  * @param {!shakaExtern.TextParserPlugin} plugin
  65.  * @export
  66.  */
  67. shaka.text.TextEngine.registerParser = function(mimeType, plugin) {
  68.   shaka.text.TextEngine.parserMap_[mimeType] = plugin;
  69. };
  72. /**
  73.  * @param {string} mimeType
  74.  * @export
  75.  */
  76. shaka.text.TextEngine.unregisterParser = function(mimeType) {
  77.   delete shaka.text.TextEngine.parserMap_[mimeType];
  78. };
  81. /**
  82.  * @param {string} mimeType
  83.  * @return {boolean}
  84.  */
  85. shaka.text.TextEngine.isTypeSupported = function(mimeType) {
  86.   return !!shaka.text.TextEngine.parserMap_[mimeType];
  87. };
  90. /** @override */
  91. shaka.text.TextEngine.prototype.destroy = function() {
  92.   this.parser_ = null;
  93.   this.displayer_ = null;
  95.   return Promise.resolve();
  96. };
  99. /**
  100.  * @param {shakaExtern.TextDisplayer} displayer
  101.  * @export
  102.  */
  103. shaka.text.TextEngine.prototype.setDisplayer = function(displayer) {
  104.   this.displayer_ = displayer;
  105. };
  108. /**
  109.  * Initialize the parser.  This can be called multiple times, but must be called
  110.  * at least once before appendBuffer.
  111.  *
  112.  * @param {string} mimeType
  113.  */
  114. shaka.text.TextEngine.prototype.initParser = function(mimeType) {
  115.   let factory = shaka.text.TextEngine.parserMap_[mimeType];
  116.   goog.asserts.assert(
  117.       factory,
  118.       'Text type negotiation should have happened already');
  119.   this.parser_ = new factory();
  120. };
  123. /**
  124.  * Parse the start time from the text media segment, if possible.
  125.  *
  126.  * @param {!ArrayBuffer} buffer
  127.  * @return {number}
  128.  * @throws {shaka.util.Error} on failure
  129.  */
  130. shaka.text.TextEngine.prototype.getStartTime = function(buffer) {
  131.   goog.asserts.assert(this.parser_, 'The parser should already be initialized');
  133.   /** @type {shakaExtern.TextParser.TimeContext} **/
  134.   let time = {
  135.     periodStart: 0,
  136.     segmentStart: null,
  137.     segmentEnd: 0
  138.   };
  140.   // Parse the buffer and extract the first cue start time.
  141.   try {
  142.     let allCues = this.parser_.parseMedia(new Uint8Array(buffer), time);
  143.     return allCues[0].startTime;
  144.   } catch (exception) {
  145.     // This could be a failure from the parser itself (init segment required)
  146.     // or an exception from allCues.length being zero.
  147.     throw new shaka.util.Error(
  148.         shaka.util.Error.Severity.CRITICAL,
  149.         shaka.util.Error.Category.TEXT,
  150.         shaka.util.Error.Code.UNABLE_TO_EXTRACT_CUE_START_TIME,
  151.         exception);
  152.   }
  153. };
  156. /**
  157.  * @param {!ArrayBuffer} buffer
  158.  * @param {?number} startTime relative to the start of the presentation
  159.  * @param {?number} endTime relative to the start of the presentation
  160.  * @return {!Promise}
  161.  */
  162. shaka.text.TextEngine.prototype.appendBuffer =
  163.     function(buffer, startTime, endTime) {
  164.   goog.asserts.assert(this.parser_, 'The parser should already be initialized');
  166.   // Start the operation asynchronously to avoid blocking the caller.
  167.   return Promise.resolve().then(function() {
  168.     // Check that TextEngine hasn't been destroyed.
  169.     if (!this.parser_ || !this.displayer_) return;
  171.     if (startTime == null || endTime == null) {
  172.       this.parser_.parseInit(new Uint8Array(buffer));
  173.       return;
  174.     }
  176.     /** @type {shakaExtern.TextParser.TimeContext} **/
  177.     let time = {
  178.       periodStart: this.timestampOffset_,
  179.       segmentStart: startTime,
  180.       segmentEnd: endTime,
  181.     };
  183.     // Parse the buffer and add the new cues.
  184.     let allCues = this.parser_.parseMedia(new Uint8Array(buffer), time);
  185.     let cuesToAppend = allCues.filter(function(cue) {
  186.       return cue.startTime >= this.appendWindowStart_ &&
  187.              cue.startTime < this.appendWindowEnd_;
  188.     }.bind(this));
  190.     this.displayer_.append(cuesToAppend);
  192.     // NOTE: We update the buffered range from the start and end times passed
  193.     // down from the segment reference, not with the start and end times of the
  194.     // parsed cues.  This is important because some segments may contain no
  195.     // cues, but we must still consider those ranges buffered.
  196.     if (this.bufferStart_ == null) {
  197.       this.bufferStart_ = Math.max(startTime, this.appendWindowStart_);
  198.     } else {
  199.       // We already had something in buffer, and we assume we are extending the
  200.       // range from the end.
  201.       goog.asserts.assert((startTime - this.bufferEnd_) <= 1,
  202.                           'There should not be a gap in text references >1s');
  203.     }
  204.     this.bufferEnd_ = Math.min(endTime, this.appendWindowEnd_);
  205.   }.bind(this));
  206. };
  209. /**
  210.  * @param {number} startTime relative to the start of the presentation
  211.  * @param {number} endTime relative to the start of the presentation
  212.  * @return {!Promise}
  213.  */
  214. shaka.text.TextEngine.prototype.remove = function(startTime, endTime) {
  215.   // Start the operation asynchronously to avoid blocking the caller.
  216.   return Promise.resolve().then(function() {
  217.     if (this.displayer_ && this.displayer_.remove(startTime, endTime)) {
  218.       if (this.bufferStart_ == null) {
  219.         goog.asserts.assert(this.bufferEnd_ == null,
  220.                             'end must be null if startTime is null');
  221.       } else {
  222.         goog.asserts.assert(this.bufferEnd_ != null,
  223.                             'end must be non-null if startTime is non-null');
  225.         // Update buffered range.
  226.         if (endTime <= this.bufferStart_ || startTime >= this.bufferEnd_) {
  227.           // No intersection.  Nothing was removed.
  228.         } else if (startTime <= this.bufferStart_ &&
  229.                    endTime >= this.bufferEnd_) {
  230.           // We wiped out everything.
  231.           this.bufferStart_ = this.bufferEnd_ = null;
  232.         } else if (startTime <= this.bufferStart_ &&
  233.                    endTime < this.bufferEnd_) {
  234.           // We removed from the beginning of the range.
  235.           this.bufferStart_ = endTime;
  236.         } else if (startTime > this.bufferStart_ &&
  237.                    endTime >= this.bufferEnd_) {
  238.           // We removed from the end of the range.
  239.           this.bufferEnd_ = startTime;
  240.         } else {
  241.           // We removed from the middle?  StreamingEngine isn't supposed to.
  242.           goog.asserts.assert(
  243.               false, 'removal from the middle is not supported by TextEngine');
  244.         }
  245.       }
  246.     }
  247.   }.bind(this));
  248. };
  251. /** @param {number} timestampOffset */
  252. shaka.text.TextEngine.prototype.setTimestampOffset =
  253.     function(timestampOffset) {
  254.   this.timestampOffset_ = timestampOffset;
  255. };
  258. /**
  259.  * @param {number} appendWindowStart
  260.  * @param {number} appendWindowEnd
  261.  */
  262. shaka.text.TextEngine.prototype.setAppendWindow =
  263.     function(appendWindowStart, appendWindowEnd) {
  264.   this.appendWindowStart_ = appendWindowStart;
  265.   this.appendWindowEnd_ = appendWindowEnd;
  266. };
  269. /**
  270.  * @return {?number} Time in seconds of the beginning of the buffered range,
  271.  *   or null if nothing is buffered.
  272.  */
  273. shaka.text.TextEngine.prototype.bufferStart = function() {
  274.   return this.bufferStart_;
  275. };
  278. /**
  279.  * @return {?number} Time in seconds of the end of the buffered range,
  280.  *   or null if nothing is buffered.
  281.  */
  282. shaka.text.TextEngine.prototype.bufferEnd = function() {
  283.   return this.bufferEnd_;
  284. };
  287. /**
  288.  * @param {number} t A timestamp
  289.  * @return {boolean}
  290.  */
  291. shaka.text.TextEngine.prototype.isBuffered = function(t) {
  292.   return t >= this.bufferStart_ && t < this.bufferEnd_;
  293. };
  296. /**
  297.  * @param {number} t A timestamp
  298.  * @return {number} Number of seconds ahead of 't' we have buffered
  299.  */
  300. shaka.text.TextEngine.prototype.bufferedAheadOf = function(t) {
  301.   if (this.bufferEnd_ == null || this.bufferEnd_ < t) return 0;
  303.   goog.asserts.assert(
  304.       this.bufferStart_ != null, 'start should not be null if end is not null');
  306.   return this.bufferEnd_ - Math.max(t, this.bufferStart_);
  307. };
  310. /**
  311.  * Append cues to text displayer.
  312.  *
  313.  * @param {!Array.<!shaka.text.Cue>} cues
  314.  * @export
  315.  */
  316. shaka.text.TextEngine.prototype.appendCues = function(cues) {
  317.   this.displayer_.append(cues);
  318. };