Source: lib/text/cue.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.text.Cue');
  9. goog.require('shaka.text.CueRegion');
  10. goog.require('shaka.util.ArrayUtils');
  13. /**
  14.  * @export
  15.  */
  16. shaka.text.Cue = class {
  17.   /**
  18.    * @param {number} startTime
  19.    * @param {number} endTime
  20.    * @param {string} payload
  21.    */
  22.   constructor(startTime, endTime, payload) {
  23.     const Cue = shaka.text.Cue;
  25.     /**
  26.      * The start time of the cue in seconds, relative to the start of the
  27.      * presentation.
  28.      * @type {number}
  29.      * @export
  30.      */
  31.     this.startTime = startTime;
  33.     /**
  34.      * The end time of the cue in seconds, relative to the start of the
  35.      * presentation.
  36.      * @type {number}
  37.      * @export
  38.      */
  39.     this.endTime = endTime;
  41.     /**
  42.      * The text payload of the cue.  If nestedCues is non-empty, this should be
  43.      * empty.  Top-level block containers should have no payload of their own.
  44.      * @type {string}
  45.      * @export
  46.      */
  47.     this.payload = payload;
  49.     /**
  50.      * The region to render the cue into.  Only supported on top-level cues,
  51.      * because nested cues are inline elements.
  52.      * @type {shaka.text.CueRegion}
  53.      * @export
  54.      */
  55.     this.region = new shaka.text.CueRegion();
  57.     /**
  58.      * The indent (in percent) of the cue box in the direction defined by the
  59.      * writing direction.
  60.      * @type {?number}
  61.      * @export
  62.      */
  63.     this.position = null;
  65.     /**
  66.      * Position alignment of the cue.
  67.      * @type {shaka.text.Cue.positionAlign}
  68.      * @export
  69.      */
  70.     this.positionAlign = Cue.positionAlign.AUTO;
  72.     /**
  73.      * Size of the cue box (in percents), where 0 means "auto".
  74.      * @type {number}
  75.      * @export
  76.      */
  77.     this.size = 0;
  79.     /**
  80.      * Alignment of the text inside the cue box.
  81.      * @type {shaka.text.Cue.textAlign}
  82.      * @export
  83.      */
  84.     this.textAlign = Cue.textAlign.CENTER;
  86.     /**
  87.      * Text direction of the cue.
  88.      * @type {shaka.text.Cue.direction}
  89.      * @export
  90.      */
  91.     this.direction = Cue.direction.HORIZONTAL_LEFT_TO_RIGHT;
  93.     /**
  94.      * Text writing mode of the cue.
  95.      * @type {shaka.text.Cue.writingMode}
  96.      * @export
  97.      */
  98.     this.writingMode = Cue.writingMode.HORIZONTAL_TOP_TO_BOTTOM;
  100.     /**
  101.      * The way to interpret line field. (Either as an integer line number or
  102.      * percentage from the display box).
  103.      * @type {shaka.text.Cue.lineInterpretation}
  104.      * @export
  105.      */
  106.     this.lineInterpretation = Cue.lineInterpretation.LINE_NUMBER;
  108.     /**
  109.      * The offset from the display box in either number of lines or
  110.      * percentage depending on the value of lineInterpretation.
  111.      * @type {?number}
  112.      * @export
  113.      */
  114.     this.line = null;
  116.     /**
  117.      * Separation between line areas inside the cue box in px or em
  118.      * (e.g. '100px'/'100em'). If not specified, this should be no less than
  119.      * the largest font size applied to the text in the cue.
  120.      * @type {string}.
  121.      * @export
  122.      */
  123.     this.lineHeight = '';
  125.     /**
  126.      * Line alignment of the cue box.
  127.      * Start alignment means the cue box’s top side (for horizontal cues), left
  128.      * side (for vertical growing right), or right side (for vertical growing
  129.      * left) is aligned at the line.
  130.      * Center alignment means the cue box is centered at the line.
  131.      * End alignment The cue box’s bottom side (for horizontal cues), right side
  132.      * (for vertical growing right), or left side (for vertical growing left) is
  133.      * aligned at the line.
  134.      * @type {shaka.text.Cue.lineAlign}
  135.      * @export
  136.      */
  137.     this.lineAlign = Cue.lineAlign.START;
  139.     /**
  140.      * Vertical alignments of the cues within their extents.
  141.      * 'BEFORE' means displaying the captions at the top of the text display
  142.      * container box, 'CENTER' means in the middle, 'AFTER' means at the bottom.
  143.      * @type {shaka.text.Cue.displayAlign}
  144.      * @export
  145.      */
  146.     this.displayAlign = Cue.displayAlign.AFTER;
  148.     /**
  149.      * Text color as a CSS color, e.g. "#FFFFFF" or "white".
  150.      * @type {string}
  151.      * @export
  152.      */
  153.     this.color = '';
  155.     /**
  156.      * Text background color as a CSS color, e.g. "#FFFFFF" or "white".
  157.      * @type {string}
  158.      * @export
  159.      */
  160.     this.backgroundColor = '';
  162.     /**
  163.      * The URL of the background image, e.g. "data:[mime type];base64,[data]".
  164.      * @type {string}
  165.      * @export
  166.      */
  167.     this.backgroundImage = '';
  169.     /**
  170.      * The border around this cue as a CSS border.
  171.      * @type {string}
  172.      * @export
  173.      */
  174.     this.border = '';
  176.     /**
  177.      * Text font size in px or em (e.g. '100px'/'100em').
  178.      * @type {string}
  179.      * @export
  180.      */
  181.     this.fontSize = '';
  183.     /**
  184.      * Text font weight. Either normal or bold.
  185.      * @type {shaka.text.Cue.fontWeight}
  186.      * @export
  187.      */
  188.     this.fontWeight = Cue.fontWeight.NORMAL;
  190.     /**
  191.      * Text font style. Normal, italic or oblique.
  192.      * @type {shaka.text.Cue.fontStyle}
  193.      * @export
  194.      */
  195.     this.fontStyle = Cue.fontStyle.NORMAL;
  197.     /**
  198.      * Text font family.
  199.      * @type {string}
  200.      * @export
  201.      */
  202.     this.fontFamily = '';
  204.     /**
  205.      * Text letter spacing as a CSS letter-spacing value.
  206.      * @type {string}
  207.      * @export
  208.      */
  209.     this.letterSpacing = '';
  211.     /**
  212.      * Text line padding as a CSS line-padding value.
  213.      * @type {string}
  214.      * @export
  215.      */
  216.     this.linePadding = '';
  218.     /**
  219.      * Opacity of the cue element, from 0-1.
  220.      * @type {number}
  221.      * @export
  222.      */
  223.     this.opacity = 1;
  225.     /**
  226.      * Text combine upright as a CSS text-combine-upright value.
  227.      * @type {string}
  228.      * @export
  229.      */
  230.     this.textCombineUpright = '';
  232.     /**
  233.      * Text decoration. A combination of underline, overline
  234.      * and line through. Empty array means no decoration.
  235.      * @type {!Array.<!shaka.text.Cue.textDecoration>}
  236.      * @export
  237.      */
  238.     this.textDecoration = [];
  240.     /**
  241.      * Text shadow color as a CSS text-shadow value.
  242.      * @type {string}
  243.      * @export
  244.      */
  245.     this.textShadow = '';
  247.     /**
  248.      * Text stroke color as a CSS color, e.g. "#FFFFFF" or "white".
  249.      * @type {string}
  250.      * @export
  251.      */
  252.     this.textStrokeColor = '';
  254.     /**
  255.      * Text stroke width as a CSS stroke-width value.
  256.      * @type {string}
  257.      * @export
  258.      */
  259.     this.textStrokeWidth = '';
  261.     /**
  262.      * Whether or not line wrapping should be applied to the cue.
  263.      * @type {boolean}
  264.      * @export
  265.      */
  266.     this.wrapLine = true;
  268.     /**
  269.      * Id of the cue.
  270.      * @type {string}
  271.      * @export
  272.      */
  273.     this.id = '';
  275.     /**
  276.      * Nested cues, which should be laid out horizontally in one block.
  277.      * Top-level cues are blocks, and nested cues are inline elements.
  278.      * Cues can be nested arbitrarily deeply.
  279.      * @type {!Array.<!shaka.text.Cue>}
  280.      * @export
  281.      */
  282.     this.nestedCues = [];
  284.     /**
  285.      * If true, this represents a container element that is "above" the main
  286.      * cues. For example, the <body> and <div> tags that contain the <p> tags
  287.      * in a TTML file. This controls the flow of the final cues; any nested cues
  288.      * within an "isContainer" cue will be laid out as separate lines.
  289.      * @type {boolean}
  290.      * @export
  291.      */
  292.     this.isContainer = false;
  294.     /**
  295.      * Whether or not the cue only acts as a line break between two nested cues.
  296.      * Should only appear in nested cues.
  297.      * @type {boolean}
  298.      * @export
  299.      */
  300.     this.lineBreak = false;
  302.     /**
  303.      * Used to indicate the type of ruby tag that should be used when rendering
  304.      * the cue. Valid values: ruby, rp, rt.
  305.      * @type {?string}
  306.      * @export
  307.      */
  308.     this.rubyTag = null;
  310.     /**
  311.      * The number of horizontal and vertical cells into which the Root Container
  312.      * Region area is divided.
  313.      *
  314.      * @type {{ columns: number, rows: number }}
  315.      * @export
  316.      */
  317.     this.cellResolution = {
  318.       columns: 32,
  319.       rows: 15,
  320.     };
  321.   }
  323.   /**
  324.    * @param {number} start
  325.    * @param {number} end
  326.    * @return {!shaka.text.Cue}
  327.    */
  328.   static lineBreak(start, end) {
  329.     const cue = new shaka.text.Cue(start, end, '');
  330.     cue.lineBreak = true;
  331.     return cue;
  332.   }
  334.   /**
  335.    * Create a copy of the cue with the same properties.
  336.    * @return {!shaka.text.Cue}
  337.    * @suppress {checkTypes} since we must use [] and "in" with a struct type.
  338.    * @export
  339.    */
  340.   clone() {
  341.     const clone = new shaka.text.Cue(0, 0, '');
  343.     for (const k in this) {
  344.       clone[k] = this[k];
  346.       // Make copies of array fields, but only one level deep.  That way, if we
  347.       // change, for instance, textDecoration on the clone, we don't affect the
  348.       // original.
  349.       if (clone[k] && clone[k].constructor == Array) {
  350.         clone[k] = /** @type {!Array} */(clone[k]).slice();
  351.       }
  352.     }
  354.     return clone;
  355.   }
  357.   /**
  358.    * Check if two Cues have all the same values in all properties.
  359.    * @param {!shaka.text.Cue} cue1
  360.    * @param {!shaka.text.Cue} cue2
  361.    * @return {boolean}
  362.    * @suppress {checkTypes} since we must use [] and "in" with a struct type.
  363.    * @export
  364.    */
  365.   static equal(cue1, cue2) {
  366.     // Compare the start time, end time and payload of the cues first for
  367.     // performance optimization.  We can avoid the more expensive recursive
  368.     // checks if the top-level properties don't match.
  369.     // See: https://github.com/shaka-project/shaka-player/issues/3018
  370.     if (cue1.startTime != cue2.startTime || cue1.endTime != cue2.endTime ||
  371.       cue1.payload != cue2.payload) {
  372.       return false;
  373.     }
  374.     for (const k in cue1) {
  375.       if (k == 'startTime' || k == 'endTime' || k == 'payload') {
  376.         // Already compared.
  377.       } else if (k == 'nestedCues') {
  378.         // This uses shaka.text.Cue.equal rather than just this.equal, since
  379.         // otherwise recursing here will unbox the method and cause "this" to be
  380.         // undefined in deeper recursion.
  381.         if (!shaka.util.ArrayUtils.equal(
  382.             cue1.nestedCues, cue2.nestedCues, shaka.text.Cue.equal)) {
  383.           return false;
  384.         }
  385.       } else if (k == 'region' || k == 'cellResolution') {
  386.         for (const k2 in cue1[k]) {
  387.           if (cue1[k][k2] != cue2[k][k2]) {
  388.             return false;
  389.           }
  390.         }
  391.       } else if (Array.isArray(cue1[k])) {
  392.         if (!shaka.util.ArrayUtils.equal(cue1[k], cue2[k])) {
  393.           return false;
  394.         }
  395.       } else {
  396.         if (cue1[k] != cue2[k]) {
  397.           return false;
  398.         }
  399.       }
  400.     }
  402.     return true;
  403.   }
  404. };
  407. /**
  408.  * @enum {string}
  409.  * @export
  410.  */
  411. shaka.text.Cue.positionAlign = {
  412.   'LEFT': 'line-left',
  413.   'RIGHT': 'line-right',
  414.   'CENTER': 'center',
  415.   'AUTO': 'auto',
  416. };
  419. /**
  420.  * @enum {string}
  421.  * @export
  422.  */
  423. shaka.text.Cue.textAlign = {
  424.   'LEFT': 'left',
  425.   'RIGHT': 'right',
  426.   'CENTER': 'center',
  427.   'START': 'start',
  428.   'END': 'end',
  429. };
  432. /**
  433.  * Vertical alignments of the cues within their extents.
  434.  * 'BEFORE' means displaying at the top of the captions container box, 'CENTER'
  435.  *  means in the middle, 'AFTER' means at the bottom.
  436.  * @enum {string}
  437.  * @export
  438.  */
  439. shaka.text.Cue.displayAlign = {
  440.   'BEFORE': 'before',
  441.   'CENTER': 'center',
  442.   'AFTER': 'after',
  443. };
  446. /**
  447.  * @enum {string}
  448.  * @export
  449.  */
  450. shaka.text.Cue.direction = {
  451.   'HORIZONTAL_LEFT_TO_RIGHT': 'ltr',
  452.   'HORIZONTAL_RIGHT_TO_LEFT': 'rtl',
  453. };
  456. /**
  457.  * @enum {string}
  458.  * @export
  459.  */
  460. shaka.text.Cue.writingMode = {
  461.   'HORIZONTAL_TOP_TO_BOTTOM': 'horizontal-tb',
  462.   'VERTICAL_LEFT_TO_RIGHT': 'vertical-lr',
  463.   'VERTICAL_RIGHT_TO_LEFT': 'vertical-rl',
  464. };
  467. /**
  468.  * @enum {number}
  469.  * @export
  470.  */
  471. shaka.text.Cue.lineInterpretation = {
  472.   'LINE_NUMBER': 0,
  473.   'PERCENTAGE': 1,
  474. };
  477. /**
  478.  * @enum {string}
  479.  * @export
  480.  */
  481. shaka.text.Cue.lineAlign = {
  482.   'CENTER': 'center',
  483.   'START': 'start',
  484.   'END': 'end',
  485. };
  488. /**
  489.  * Default text color according to
  490.  * https://w3c.github.io/webvtt/#default-text-color
  491.  * @enum {string}
  492.  * @export
  493.  */
  494. shaka.text.Cue.defaultTextColor = {
  495.   'white': 'white',
  496.   'lime': 'lime',
  497.   'cyan': 'cyan',
  498.   'red': 'red',
  499.   'yellow': 'yellow',
  500.   'magenta': 'magenta',
  501.   'blue': 'blue',
  502.   'black': 'black',
  503. };
  506. /**
  507.  * Default text background color according to
  508.  * https://w3c.github.io/webvtt/#default-text-background
  509.  * @enum {string}
  510.  * @export
  511.  */
  512. shaka.text.Cue.defaultTextBackgroundColor = {
  513.   'bg_white': 'white',
  514.   'bg_lime': 'lime',
  515.   'bg_cyan': 'cyan',
  516.   'bg_red': 'red',
  517.   'bg_yellow': 'yellow',
  518.   'bg_magenta': 'magenta',
  519.   'bg_blue': 'blue',
  520.   'bg_black': 'black',
  521. };
  524. /**
  525.  * In CSS font weight can be a number, where 400 is normal and 700 is bold.
  526.  * Use these values for the enum for consistency.
  527.  * @enum {number}
  528.  * @export
  529.  */
  530. shaka.text.Cue.fontWeight = {
  531.   'NORMAL': 400,
  532.   'BOLD': 700,
  533. };
  536. /**
  537.  * @enum {string}
  538.  * @export
  539.  */
  540. shaka.text.Cue.fontStyle = {
  541.   'NORMAL': 'normal',
  542.   'ITALIC': 'italic',
  543.   'OBLIQUE': 'oblique',
  544. };
  547. /**
  548.  * @enum {string}
  549.  * @export
  550.  */
  551. shaka.text.Cue.textDecoration = {
  552.   'UNDERLINE': 'underline',
  553.   'LINE_THROUGH': 'lineThrough',
  554.   'OVERLINE': 'overline',
  555. };