Source: externs/shaka/text.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  8. /**
  9.  * @externs
  10.  */
  13. /**
  14.  * @interface
  15.  * @exportDoc
  16.  */
  17. shaka.extern.CueRegion = class {
  18.   constructor() {
  19.     /**
  20.      * Region identifier.
  21.      * @type {string}
  22.      * @exportDoc
  23.      */
  24.     this.id;
  26.     /**
  27.      * The X offset to start the rendering area in viewportAnchorUnits of the
  28.      * video width.
  29.      * @type {number}
  30.      * @exportDoc
  31.      */
  32.     this.viewportAnchorX;
  34.     /**
  35.      * The X offset to start the rendering area in viewportAnchorUnits of the
  36.      * video height.
  37.      * @type {number}
  38.      * @exportDoc
  39.      */
  40.     this.viewportAnchorY;
  42.     /**
  43.      * The X offset to start the rendering area in percentage (0-100) of this
  44.      * region width.
  45.      * @type {number}
  46.      * @exportDoc
  47.      */
  48.     this.regionAnchorX;
  50.     /**
  51.      * The Y offset to start the rendering area in percentage (0-100) of the
  52.      * region height.
  53.      * @type {number}
  54.      * @exportDoc
  55.      */
  56.     this.regionAnchorY;
  58.     /**
  59.      * The width of the rendering area in widthUnits.
  60.      * @type {number}
  61.      * @exportDoc
  62.      */
  63.     this.width;
  65.     /**
  66.      * The width of the rendering area in heightUnits.
  67.      * @type {number}
  68.      * @exportDoc
  69.      */
  70.     this.height;
  72.     /**
  73.      * The units (percentage, pixels or lines) the region height is in.
  74.      * @type {shaka.text.CueRegion.units}
  75.      * @exportDoc
  76.      */
  77.     this.heightUnits;
  79.     /**
  80.      * The units (percentage or pixels) the region width is in.
  81.      * @type {shaka.text.CueRegion.units}
  82.      * @exportDoc
  83.      */
  84.     this.widthUnits;
  86.     /**
  87.      * The units (percentage or pixels) the region viewportAnchors are in.
  88.      * @type {shaka.text.CueRegion.units}
  89.      * @exportDoc
  90.      */
  91.     this.viewportAnchorUnits;
  93.     /**
  94.      * If scroll=UP, it means that cues in the region will be added to the
  95.      * bottom of the region and will push any already displayed cues in the
  96.      * region up.  Otherwise (scroll=NONE) cues will stay fixed at the location
  97.      * they were first painted in.
  98.      * @type {shaka.text.CueRegion.scrollMode}
  99.      * @exportDoc
  100.      */
  101.     this.scroll;
  102.   }
  103. };
  106. /**
  107.  * @interface
  108.  * @exportDoc
  109.  */
  110. shaka.extern.Cue = class {
  111.   constructor() {
  112.     /**
  113.      * The start time of the cue in seconds, relative to the start of the
  114.      * presentation.
  115.      * @type {number}
  116.      * @exportDoc
  117.      */
  118.     this.startTime;
  120.     /**
  121.      * The end time of the cue in seconds, relative to the start of the
  122.      * presentation.
  123.      * @type {number}
  124.      * @exportDoc
  125.      */
  126.     this.endTime;
  128.     /**
  129.      * The text payload of the cue.  If nestedCues is non-empty, this should be
  130.      * empty.  Top-level block containers should have no payload of their own.
  131.      * @type {string}
  132.      * @exportDoc
  133.      */
  134.     this.payload;
  136.     /**
  137.      * The region to render the cue into.  Only supported on top-level cues,
  138.      * because nested cues are inline elements.
  139.      * @type {shaka.extern.CueRegion}
  140.      * @exportDoc
  141.      */
  142.     this.region;
  144.     /**
  145.      * The indent (in percent) of the cue box in the direction defined by the
  146.      * writing direction.
  147.      * @type {?number}
  148.      * @exportDoc
  149.      */
  150.     this.position;
  152.     /**
  153.      * Position alignment of the cue.
  154.      * @type {shaka.text.Cue.positionAlign}
  155.      * @exportDoc
  156.      */
  157.     this.positionAlign;
  159.     /**
  160.      * Size of the cue box (in percents), where 0 means "auto".
  161.      * @type {number}
  162.      * @exportDoc
  163.      */
  164.     this.size;
  166.     /**
  167.      * Alignment of the text inside the cue box.
  168.      * @type {shaka.text.Cue.textAlign}
  169.      * @exportDoc
  170.      */
  171.     this.textAlign;
  173.     /**
  174.      * Text direction of the cue.
  175.      * @type {shaka.text.Cue.direction}
  176.      * @exportDoc
  177.      */
  178.     this.direction;
  180.     /**
  181.      * Text writing mode of the cue.
  182.      * @type {shaka.text.Cue.writingMode}
  183.      * @exportDoc
  184.      */
  185.     this.writingMode;
  187.     /**
  188.      * The way to interpret line field. (Either as an integer line number or
  189.      * percentage from the display box).
  190.      * @type {shaka.text.Cue.lineInterpretation}
  191.      * @exportDoc
  192.      */
  193.     this.lineInterpretation;
  195.     /**
  196.      * The offset from the display box in either number of lines or
  197.      * percentage depending on the value of lineInterpretation.
  198.      * @type {?number}
  199.      * @exportDoc
  200.      */
  201.     this.line;
  203.     /**
  204.      * Separation between line areas inside the cue box in px or em
  205.      * (e.g. '100px'/'100em'). If not specified, this should be no less than
  206.      * the largest font size applied to the text in the cue.
  207.      * @type {string}.
  208.      * @exportDoc
  209.      */
  210.     this.lineHeight;
  212.     /**
  213.      * Line alignment of the cue box.
  214.      * Start alignment means the cue box’s top side (for horizontal cues), left
  215.      * side (for vertical growing right), or right side (for vertical growing
  216.      * left) is aligned at the line.
  217.      * Center alignment means the cue box is centered at the line.
  218.      * End alignment The cue box’s bottom side (for horizontal cues), right side
  219.      * (for vertical growing right), or left side (for vertical growing left) is
  220.      * aligned at the line.
  221.      * @type {shaka.text.Cue.lineAlign}
  222.      * @exportDoc
  223.      */
  224.     this.lineAlign;
  226.     /**
  227.      * Vertical alignments of the cues within their extents.
  228.      * 'BEFORE' means displaying the captions at the top of the text display
  229.      * container box, 'CENTER' means in the middle, 'AFTER' means at the bottom.
  230.      * @type {shaka.text.Cue.displayAlign}
  231.      * @exportDoc
  232.      */
  233.     this.displayAlign;
  235.     /**
  236.      * Text color as a CSS color, e.g. "#FFFFFF" or "white".
  237.      * @type {string}
  238.      * @exportDoc
  239.      */
  240.     this.color;
  242.     /**
  243.      * Text background color as a CSS color, e.g. "#FFFFFF" or "white".
  244.      * @type {string}
  245.      * @exportDoc
  246.      */
  247.     this.backgroundColor;
  249.     /**
  250.      * The number of horizontal and vertical cells into which the Root Container
  251.      * Region area is divided.
  252.      *
  253.      * @type {{ columns: number, rows: number }}
  254.      * @exportDoc
  255.      */
  256.     this.cellResolution;
  258.     /**
  259.      * The URL of the background image, e.g. "data:[mime type];base64,[data]".
  260.      * @type {string}
  261.      * @exportDoc
  262.      */
  263.     this.backgroundImage;
  265.     /**
  266.      * The border around this cue as a CSS border.
  267.      * @type {string}
  268.      * @exportDoc
  269.      */
  270.     this.border;
  272.     /**
  273.      * Text font size in px or em (e.g. '100px'/'100em').
  274.      * @type {string}
  275.      * @exportDoc
  276.      */
  277.     this.fontSize;
  279.     /**
  280.      * Text font weight. Either normal or bold.
  281.      * @type {shaka.text.Cue.fontWeight}
  282.      * @exportDoc
  283.      */
  284.     this.fontWeight;
  286.     /**
  287.      * Text font style. Normal, italic or oblique.
  288.      * @type {shaka.text.Cue.fontStyle}
  289.      * @exportDoc
  290.      */
  291.     this.fontStyle;
  293.     /**
  294.      * Text font family.
  295.      * @type {string}
  296.      * @exportDoc
  297.      */
  298.     this.fontFamily;
  300.     /**
  301.      * Text shadow color as a CSS text-shadow value.
  302.      * @type {string}
  303.      * @exportDoc
  304.      */
  305.     this.textShadow = '';
  307.     /**
  308.      * Text stroke color as a CSS color, e.g. "#FFFFFF" or "white".
  309.      * @type {string}
  310.      * @exportDoc
  311.      */
  312.     this.textStrokeColor;
  314.     /**
  315.      * Text stroke width as a CSS stroke-width value.
  316.      * @type {string}
  317.      * @exportDoc
  318.      */
  319.     this.textStrokeWidth;
  321.     /**
  322.      * Text letter spacing as a CSS letter-spacing value.
  323.      * @type {string}
  324.      * @exportDoc
  325.      */
  326.     this.letterSpacing;
  328.     /**
  329.      * Text line padding as a CSS line-padding value.
  330.      * @type {string}
  331.      * @exportDoc
  332.      */
  333.     this.linePadding;
  335.     /**
  336.      * Opacity of the cue element, from 0-1.
  337.      * @type {number}
  338.      * @exportDoc
  339.      */
  340.     this.opacity;
  342.     /**
  343.      * Text decoration. A combination of underline, overline
  344.      * and line through. Empty array means no decoration.
  345.      * @type {!Array.<!shaka.text.Cue.textDecoration>}
  346.      * @exportDoc
  347.      */
  348.     this.textDecoration;
  350.     /**
  351.      * Whether or not line wrapping should be applied to the cue.
  352.      * @type {boolean}
  353.      * @exportDoc
  354.      */
  355.     this.wrapLine;
  357.     /**
  358.      * Id of the cue.
  359.      * @type {string}
  360.      * @exportDoc
  361.      */
  362.     this.id;
  364.     /**
  365.      * Nested cues, which should be laid out horizontally in one block.
  366.      * Top-level cues are blocks, and nested cues are inline elements.
  367.      * Cues can be nested arbitrarily deeply.
  368.      * @type {!Array.<!shaka.extern.Cue>}
  369.      * @exportDoc
  370.      */
  371.     this.nestedCues;
  373.     /**
  374.      * If true, this represents a container element that is "above" the main
  375.      * cues. For example, the <body> and <div> tags that contain the <p> tags
  376.      * in a TTML file. This controls the flow of the final cues; any nested cues
  377.      * within an "isContainer" cue will be laid out as separate lines.
  378.      * @type {boolean}
  379.      * @exportDoc
  380.      */
  381.     this.isContainer;
  383.     /**
  384.      * Whether or not the cue only acts as a line break between two nested cues.
  385.      * Should only appear in nested cues.
  386.      * @type {boolean}
  387.      * @exportDoc
  388.      */
  389.     this.lineBreak;
  390.   }
  391. };
  394. /**
  395.  * An interface for plugins that parse text tracks.
  396.  *
  397.  * @interface
  398.  * @exportDoc
  399.  */
  400. shaka.extern.TextParser = class {
  401.   /**
  402.    * Parse an initialization segment. Some formats do not have init
  403.    * segments so this won't always be called.
  404.    *
  405.    * @param {!Uint8Array} data
  406.    *    The data that makes up the init segment.
  407.    *
  408.    * @exportDoc
  409.    */
  410.   parseInit(data) {}
  412.   /**
  413.    * Parse a media segment and return the cues that make up the segment.
  414.    *
  415.    * @param {!Uint8Array} data
  416.    *    The next section of buffer.
  417.    * @param {shaka.extern.TextParser.TimeContext} timeContext
  418.    *    The time information that should be used to adjust the times values
  419.    *    for each cue.
  420.    * @param {?(string|undefined)} uri
  421.    *    The media uri.
  422.    * @return {!Array.<!shaka.extern.Cue>}
  423.    *
  424.    * @exportDoc
  425.    */
  426.   parseMedia(data, timeContext, uri) {}
  428.   /**
  429.    * Notifies the stream if the manifest is in sequence mode or not.
  430.    *
  431.    * @param {boolean} sequenceMode
  432.    */
  433.   setSequenceMode(sequenceMode) {}
  434. };
  437. /**
  438.  * A collection of time offsets used to adjust text cue times.
  439.  *
  440.  * @typedef {{
  441.  *   periodStart: number,
  442.  *   segmentStart: number,
  443.  *   segmentEnd: number,
  444.  *   vttOffset: number
  445.  * }}
  446.  *
  447.  * @property {number} periodStart
  448.  *     The absolute start time of the period in seconds.
  449.  * @property {number} segmentStart
  450.  *     The absolute start time of the segment in seconds.
  451.  * @property {number} segmentEnd
  452.  *     The absolute end time of the segment in seconds.
  453.  * @property {number} vttOffset
  454.  *     The start time relative to either segment or period start depending
  455.  *     on <code>segmentRelativeVttTiming</code> configuration.
  456.  *
  457.  * @exportDoc
  458.  */
  459. shaka.extern.TextParser.TimeContext;
  462. /**
  463.  * @typedef {function():!shaka.extern.TextParser}
  464.  * @exportDoc
  465.  */
  466. shaka.extern.TextParserPlugin;
  469. /**
  470.  * @summary
  471.  * An interface for plugins that display text.
  472.  *
  473.  * @description
  474.  * This should handle displaying the text cues on the page.  This is given the
  475.  * cues to display and told when to start and stop displaying.  This should only
  476.  * display the cues it is given and remove cues when told to.
  477.  *
  478.  * <p>
  479.  * This should only change whether it is displaying the cues through the
  480.  * <code>setTextVisibility</code> function; the app should not change the text
  481.  * visibility outside the top-level Player methods.  If you really want to
  482.  * control text visibility outside the Player methods, you must set the
  483.  * <code>streaming.alwaysStreamText</code> Player configuration value to
  484.  * <code>true</code>.
  485.  *
  486.  * @interface
  487.  * @extends {shaka.util.IDestroyable}
  488.  * @exportDoc
  489.  */
  490. shaka.extern.TextDisplayer = class {
  491.   /**
  492.    * @override
  493.    * @exportDoc
  494.    */
  495.   destroy() {}
  497.   /**
  498.    * Append given text cues to the list of cues to be displayed.
  499.    *
  500.    * @param {!Array.<!shaka.text.Cue>} cues
  501.    *    Text cues to be appended.
  502.    *
  503.    * @exportDoc
  504.    */
  505.   append(cues) {}
  507.   /**
  508.    * Remove all cues that are fully contained by the given time range (relative
  509.    * to the presentation). <code>endTime</code> will be greater to equal to
  510.    * <code>startTime</code>.  <code>remove</code> should only return
  511.    * <code>false</code> if the displayer has been destroyed. If the displayer
  512.    * has not been destroyed <code>remove</code> should return <code>true</code>.
  513.    *
  514.    * @param {number} startTime
  515.    * @param {number} endTime
  516.    *
  517.    * @return {boolean}
  518.    *
  519.    * @exportDoc
  520.    */
  521.   remove(startTime, endTime) {}
  523.   /**
  524.    * Returns true if text is currently visible.
  525.    *
  526.    * @return {boolean}
  527.    *
  528.    * @exportDoc
  529.    */
  530.   isTextVisible() {}
  532.   /**
  533.    * Set text visibility.
  534.    *
  535.    * @param {boolean} on
  536.    *
  537.    * @exportDoc
  538.    */
  539.   setTextVisibility(on) {}
  540. };
  543. /**
  544.  * A factory for creating a TextDisplayer.
  545.  *
  546.  * @typedef {function():!shaka.extern.TextDisplayer}
  547.  * @exportDoc
  548.  */
  549. shaka.extern.TextDisplayer.Factory;