Source: lib/text/vtt_text_parser.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.text.VttTextParser');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.media.ManifestParser');
  12. goog.require('shaka.text.Cue');
  13. goog.require('shaka.text.CueRegion');
  14. goog.require('shaka.text.TextEngine');
  15. goog.require('shaka.util.Error');
  16. goog.require('shaka.util.StringUtils');
  17. goog.require('shaka.util.TextParser');
  20. /**
  21.  * @implements {shaka.extern.TextParser}
  22.  * @export
  23.  */
  24. shaka.text.VttTextParser = class {
  25.   /** Constructs a VTT parser. */
  26.   constructor() {
  27.     /** @private {boolean} */
  28.     this.sequenceMode_ = false;
  30.     /** @private {string} */
  31.     this.manifestType_ = shaka.media.ManifestParser.UNKNOWN;
  32.   }
  34.   /**
  35.    * @override
  36.    * @export
  37.    */
  38.   parseInit(data) {
  39.     goog.asserts.assert(false, 'VTT does not have init segments');
  40.   }
  42.   /**
  43.    * @override
  44.    * @export
  45.    */
  46.   setSequenceMode(sequenceMode) {
  47.     this.sequenceMode_ = sequenceMode;
  48.   }
  50.   /**
  51.    * @override
  52.    * @export
  53.    */
  54.   setManifestType(manifestType) {
  55.     this.manifestType_ = manifestType;
  56.   }
  58.   /**
  59.    * @override
  60.    * @export
  61.    */
  62.   parseMedia(data, time) {
  63.     const VttTextParser = shaka.text.VttTextParser;
  64.     // Get the input as a string.  Normalize newlines to \n.
  65.     let str = shaka.util.StringUtils.fromUTF8(data);
  66.     str = str.replace(/\r\n|\r(?=[^\n]|$)/gm, '\n');
  67.     const blocks = str.split(/\n{2,}/m);
  69.     if (!/^WEBVTT($|[ \t\n])/m.test(blocks[0])) {
  70.       throw new shaka.util.Error(
  71.           shaka.util.Error.Severity.CRITICAL,
  72.           shaka.util.Error.Category.TEXT,
  73.           shaka.util.Error.Code.INVALID_TEXT_HEADER);
  74.     }
  76.     // Depending on "segmentRelativeVttTiming" configuration,
  77.     // "vttOffset" will correspond to either "periodStart" (default)
  78.     // or "segmentStart", for segmented VTT where timings are relative
  79.     // to the beginning of each segment.
  80.     // NOTE: "periodStart" is the timestamp offset applied via TextEngine.
  81.     // It is no longer closely tied to periods, but the name stuck around.
  82.     // NOTE: This offset and the flag choosing its meaning have no effect on
  83.     // HLS content, which should use X-TIMESTAMP-MAP and periodStart instead.
  84.     let offset = time.vttOffset;
  86.     if (this.manifestType_ == shaka.media.ManifestParser.HLS) {
  87.       // Only use 'X-TIMESTAMP-MAP' with HLS.
  88.       if (blocks[0].includes('X-TIMESTAMP-MAP')) {
  89.         offset = this.computeHlsOffset_(blocks[0], time);
  90.       } else if (time.periodStart && time.vttOffset == time.periodStart) {
  91.         // In the case where X-TIMESTAMP-MAP is not used and it is HLS, we
  92.         // should not use offset unless segment-relative times are used.
  93.         offset = 0;
  94.       }
  95.     }
  97.     // Parse VTT regions.
  98.     /* !Array<!shaka.text.CueRegion> */
  99.     const regions = [];
  100.     for (const line of blocks[0].split('\n')) {
  101.       if (/^Region:/.test(line)) {
  102.         const region = VttTextParser.parseRegion_(line);
  103.         regions.push(region);
  104.       }
  105.     }
  107.     /** @type {!Map<string, !shaka.text.Cue>} */
  108.     const styles = new Map();
  109.     shaka.text.Cue.addDefaultTextColor(styles);
  111.     // Parse cues.
  112.     const ret = [];
  113.     for (const block of blocks.slice(1)) {
  114.       const lines = block.split('\n');
  115.       VttTextParser.parseStyle_(lines, styles);
  116.       const cue = VttTextParser.parseCue_(lines, offset, regions, styles);
  117.       if (cue) {
  118.         ret.push(cue);
  119.       }
  120.     }
  122.     return ret;
  123.   }
  125.   /**
  126.    * @param {string} headerBlock Contains X-TIMESTAMP-MAP.
  127.    * @param {shaka.extern.TextParser.TimeContext} time
  128.    * @return {number}
  129.    * @private
  130.    */
  131.   computeHlsOffset_(headerBlock, time) {
  132.     // https://bit.ly/2K92l7y
  133.     // The 'X-TIMESTAMP-MAP' header is used in HLS to align text with
  134.     // the rest of the media.
  135.     // The header format is 'X-TIMESTAMP-MAP=MPEGTS:n,LOCAL:m'
  136.     // (the attributes can go in any order)
  137.     // where n is MPEG-2 time and m is cue time it maps to.
  138.     // For example 'X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:900000'
  139.     // means an offset of 10 seconds
  140.     // 900000/MPEG_TIMESCALE - cue time.
  141.     const cueTimeMatch = headerBlock.match(
  142.         /LOCAL:((?:(\d{1,}):)?(\d{2}):(\d{2})\.(\d{3}))/m);
  143.     const mpegTimeMatch = headerBlock.match(/MPEGTS:(\d+)/m);
  145.     if (!cueTimeMatch || !mpegTimeMatch) {
  146.       throw new shaka.util.Error(
  147.           shaka.util.Error.Severity.CRITICAL,
  148.           shaka.util.Error.Category.TEXT,
  149.           shaka.util.Error.Code.INVALID_TEXT_HEADER);
  150.     }
  152.     const cueTime = shaka.util.TextParser.parseTime(cueTimeMatch[1]);
  153.     if (cueTime == null) {
  154.       throw new shaka.util.Error(
  155.           shaka.util.Error.Severity.CRITICAL,
  156.           shaka.util.Error.Category.TEXT,
  157.           shaka.util.Error.Code.INVALID_TEXT_HEADER);
  158.     }
  160.     let mpegTime = Number(mpegTimeMatch[1]);
  161.     const mpegTimescale = shaka.text.VttTextParser.MPEG_TIMESCALE_;
  163.     const rolloverSeconds =
  164.         shaka.text.VttTextParser.TS_ROLLOVER_ / mpegTimescale;
  165.     let segmentStart = time.segmentStart - time.periodStart;
  166.     while (segmentStart >= rolloverSeconds) {
  167.       segmentStart -= rolloverSeconds;
  168.       mpegTime += shaka.text.VttTextParser.TS_ROLLOVER_;
  169.     }
  171.     return time.periodStart + mpegTime / mpegTimescale - cueTime;
  172.   }
  174.   /**
  175.    * Parses a string into a Region object.
  176.    *
  177.    * @param {string} text
  178.    * @return {!shaka.text.CueRegion}
  179.    * @private
  180.    */
  181.   static parseRegion_(text) {
  182.     const VttTextParser = shaka.text.VttTextParser;
  183.     const parser = new shaka.util.TextParser(text);
  184.     // The region string looks like this:
  185.     // Region: id=fred width=50% lines=3 regionanchor=0%,100%
  186.     //         viewportanchor=10%,90% scroll=up
  187.     const region = new shaka.text.CueRegion();
  189.     // Skip 'Region:'
  190.     parser.readWord();
  191.     parser.skipWhitespace();
  193.     let word = parser.readWord();
  194.     while (word) {
  195.       if (!VttTextParser.parseRegionSetting_(region, word)) {
  196.         shaka.log.warning(
  197.             'VTT parser encountered an invalid VTTRegion setting: ', word,
  198.             ' The setting will be ignored.');
  199.       }
  200.       parser.skipWhitespace();
  201.       word = parser.readWord();
  202.     }
  204.     return region;
  205.   }
  207.   /**
  208.    * Parses a style block into a Cue object.
  209.    *
  210.    * @param {!Array<string>} text
  211.    * @param {!Map<string, !shaka.text.Cue>} styles
  212.    * @private
  213.    */
  214.   static parseStyle_(text, styles) {
  215.     // Skip empty blocks.
  216.     if (text.length == 1 && !text[0]) {
  217.       return;
  218.     }
  220.     // Skip comment blocks.
  221.     if (/^NOTE($|[ \t])/.test(text[0])) {
  222.       return;
  223.     }
  225.     // Only style block are allowed.
  226.     if (text[0] != 'STYLE') {
  227.       return;
  228.     }
  230.     /** @type {!Array<!Array<string>>} */
  231.     const styleBlocks = [];
  232.     let lastBlockIndex = -1;
  233.     for (let i = 1; i < text.length; i++) {
  234.       if (text[i].includes('::cue')) {
  235.         styleBlocks.push([]);
  236.         lastBlockIndex = styleBlocks.length - 1;
  237.       }
  238.       if (lastBlockIndex == -1) {
  239.         continue;
  240.       }
  241.       styleBlocks[lastBlockIndex].push(text[i]);
  242.       if (text[i].includes('}')) {
  243.         lastBlockIndex = -1;
  244.       }
  245.     }
  247.     for (const styleBlock of styleBlocks) {
  248.       let styleSelector = 'global';
  249.       // Look for what is within parentheses. For example:
  250.       // <code>:: cue (b) {</code>, what we are looking for is <code>b</code>
  251.       const selector = styleBlock[0].match(/\((.*)\)/);
  252.       if (selector) {
  253.         styleSelector = selector.pop();
  254.       }
  256.       // We start at 1 to avoid '::cue' and end earlier to avoid '}'
  257.       let propertyLines = styleBlock.slice(1, -1);
  258.       if (styleBlock[0].includes('}')) {
  259.         const payload = /\{(.*?)\}/.exec(styleBlock[0]);
  260.         if (payload) {
  261.           propertyLines = payload[1].split(';');
  262.         }
  263.       }
  265.       // Continue styles over multiple selectors if necessary.
  266.       // For example,
  267.       //   ::cue(b) { background: white; } ::cue(b) { color: blue; }
  268.       // should set both the background and foreground of bold tags.
  269.       let cue = styles.get(styleSelector);
  270.       if (!cue) {
  271.         cue = new shaka.text.Cue(0, 0, '');
  272.       }
  274.       let validStyle = false;
  275.       for (let i = 0; i < propertyLines.length; i++) {
  276.         // We look for CSS properties. As a general rule they are separated by
  277.         // <code>:</code>. Eg: <code>color: red;</code>
  278.         const lineParts = /^\s*([^:]+):\s*(.*)/.exec(propertyLines[i]);
  279.         if (lineParts) {
  280.           const name = lineParts[1].trim();
  281.           const value = lineParts[2].trim().replace(';', '');
  282.           switch (name) {
  283.             case 'background-color':
  284.             case 'background':
  285.               validStyle = true;
  286.               cue.backgroundColor = value;
  287.               break;
  288.             case 'color':
  289.               validStyle = true;
  290.               cue.color = value;
  291.               break;
  292.             case 'font-family':
  293.               validStyle = true;
  294.               cue.fontFamily = value;
  295.               break;
  296.             case 'font-size':
  297.               validStyle = true;
  298.               cue.fontSize = value;
  299.               break;
  300.             case 'font-weight':
  301.               if (parseInt(value, 10) >= 700 || value == 'bold') {
  302.                 validStyle = true;
  303.                 cue.fontWeight = shaka.text.Cue.fontWeight.BOLD;
  304.               }
  305.               break;
  306.             case 'font-style':
  307.               switch (value) {
  308.                 case 'normal':
  309.                   validStyle = true;
  310.                   cue.fontStyle = shaka.text.Cue.fontStyle.NORMAL;
  311.                   break;
  312.                 case 'italic':
  313.                   validStyle = true;
  314.                   cue.fontStyle = shaka.text.Cue.fontStyle.ITALIC;
  315.                   break;
  316.                 case 'oblique':
  317.                   validStyle = true;
  318.                   cue.fontStyle = shaka.text.Cue.fontStyle.OBLIQUE;
  319.                   break;
  320.               }
  321.               break;
  322.             case 'opacity':
  323.               validStyle = true;
  324.               cue.opacity = parseFloat(value);
  325.               break;
  326.             case 'text-combine-upright':
  327.               validStyle = true;
  328.               cue.textCombineUpright = value;
  329.               break;
  330.             case 'text-shadow':
  331.               validStyle = true;
  332.               cue.textShadow = value;
  333.               break;
  334.             case 'white-space':
  335.               validStyle = true;
  336.               cue.wrapLine = value != 'noWrap';
  337.               break;
  338.             default:
  339.               shaka.log.warning('VTT parser encountered an unsupported style: ',
  340.                   lineParts);
  341.               break;
  342.           }
  343.         }
  344.       }
  346.       if (validStyle) {
  347.         styles.set(styleSelector, cue);
  348.       }
  349.     }
  350.   }
  352.   /**
  353.    * Parses a text block into a Cue object.
  354.    *
  355.    * @param {!Array<string>} text
  356.    * @param {number} timeOffset
  357.    * @param {!Array<!shaka.text.CueRegion>} regions
  358.    * @param {!Map<string, !shaka.text.Cue>} styles
  359.    * @return {shaka.text.Cue}
  360.    * @private
  361.    */
  362.   static parseCue_(text, timeOffset, regions, styles) {
  363.     const VttTextParser = shaka.text.VttTextParser;
  365.     // Skip empty blocks.
  366.     if (text.length == 1 && !text[0]) {
  367.       return null;
  368.     }
  370.     // Skip comment blocks.
  371.     if (/^NOTE($|[ \t])/.test(text[0])) {
  372.       return null;
  373.     }
  375.     // Skip style and region blocks.
  376.     if (text[0] == 'STYLE' || text[0] == 'REGION') {
  377.       return null;
  378.     }
  380.     let id = null;
  381.     if (!text[0].includes('-->')) {
  382.       id = text[0];
  383.       text.splice(0, 1);
  384.     }
  386.     // Parse the times.
  387.     const parser = new shaka.util.TextParser(text[0]);
  388.     let start = parser.parseTime();
  389.     const expect = parser.readRegex(/[ \t]+-->[ \t]+/g);
  390.     let end = parser.parseTime();
  392.     if (start == null || expect == null || end == null) {
  393.       shaka.log.alwaysWarn(
  394.           'Failed to parse VTT time code. Cue skipped:', id, text);
  395.       return null;
  396.     }
  398.     start += timeOffset;
  399.     end += timeOffset;
  401.     // Get the payload.
  402.     const payload = text.slice(1).join('\n').trim();
  404.     let cue = null;
  405.     if (styles.has('global')) {
  406.       cue = styles.get('global').clone();
  407.       cue.startTime = start;
  408.       cue.endTime = end;
  409.       cue.payload = payload;
  410.     } else {
  411.       cue = new shaka.text.Cue(start, end, payload);
  412.     }
  414.     // Parse optional settings.
  415.     parser.skipWhitespace();
  416.     let word = parser.readWord();
  417.     while (word) {
  418.       if (!VttTextParser.parseCueSetting(cue, word, regions)) {
  419.         shaka.log.warning('VTT parser encountered an invalid VTT setting: ',
  420.             word,
  421.             ' The setting will be ignored.');
  422.       }
  423.       parser.skipWhitespace();
  424.       word = parser.readWord();
  425.     }
  427.     shaka.text.Cue.parseCuePayload(cue, styles);
  429.     if (id != null) {
  430.       cue.id = id;
  431.     }
  432.     return cue;
  433.   }
  435.   /**
  436.    * Parses a WebVTT setting from the given word.
  437.    *
  438.    * @param {!shaka.text.Cue} cue
  439.    * @param {string} word
  440.    * @param {!Array<!shaka.text.CueRegion>} regions
  441.    * @return {boolean} True on success.
  442.    */
  443.   static parseCueSetting(cue, word, regions) {
  444.     const VttTextParser = shaka.text.VttTextParser;
  445.     let results = null;
  446.     if ((results = /^align:(start|middle|center|end|left|right)$/.exec(word))) {
  447.       VttTextParser.setTextAlign_(cue, results[1]);
  448.     } else if ((results = /^vertical:(lr|rl)$/.exec(word))) {
  449.       VttTextParser.setVerticalWritingMode_(cue, results[1]);
  450.     } else if ((results = /^size:([\d.]+)%$/.exec(word))) {
  451.       cue.size = Number(results[1]);
  452.     } else if ((results =
  453.         // eslint-disable-next-line max-len
  454.         /^position:([\d.]+)%(?:,(line-left|line-right|middle|center|start|end|auto))?$/
  455.             .exec(word))) {
  456.       cue.position = Number(results[1]);
  457.       if (results[2]) {
  458.         VttTextParser.setPositionAlign_(cue, results[2]);
  459.       }
  460.     } else if ((results = /^region:(.*)$/.exec(word))) {
  461.       const region = VttTextParser.getRegionById_(regions, results[1]);
  462.       if (region) {
  463.         cue.region = region;
  464.       }
  465.     } else {
  466.       return VttTextParser.parsedLineValueAndInterpretation_(cue, word);
  467.     }
  469.     return true;
  470.   }
  472.   /**
  473.    *
  474.    * @param {!Array<!shaka.text.CueRegion>} regions
  475.    * @param {string} id
  476.    * @return {?shaka.text.CueRegion}
  477.    * @private
  478.    */
  479.   static getRegionById_(regions, id) {
  480.     const regionsWithId = regions.filter((region) => {
  481.       return region.id == id;
  482.     });
  483.     if (!regionsWithId.length) {
  484.       shaka.log.warning('VTT parser could not find a region with id: ',
  485.           id,
  486.           ' The region will be ignored.');
  487.       return null;
  488.     }
  489.     goog.asserts.assert(regionsWithId.length == 1,
  490.         'VTTRegion ids should be unique!');
  492.     return regionsWithId[0];
  493.   }
  495.   /**
  496.    * Parses a WebVTTRegion setting from the given word.
  497.    *
  498.    * @param {!shaka.text.CueRegion} region
  499.    * @param {string} word
  500.    * @return {boolean} True on success.
  501.    * @private
  502.    */
  503.   static parseRegionSetting_(region, word) {
  504.     let results = null;
  505.     if ((results = /^id=(.*)$/.exec(word))) {
  506.       region.id = results[1];
  507.     } else if ((results = /^width=(\d{1,2}|100)%$/.exec(word))) {
  508.       region.width = Number(results[1]);
  509.     } else if ((results = /^lines=(\d+)$/.exec(word))) {
  510.       region.height = Number(results[1]);
  511.       region.heightUnits = shaka.text.CueRegion.units.LINES;
  512.     } else if ((results = /^regionanchor=(\d{1,2}|100)%,(\d{1,2}|100)%$/
  513.         .exec(word))) {
  514.       region.regionAnchorX = Number(results[1]);
  515.       region.regionAnchorY = Number(results[2]);
  516.     } else if ((results = /^viewportanchor=(\d{1,2}|100)%,(\d{1,2}|100)%$/
  517.         .exec(word))) {
  518.       region.viewportAnchorX = Number(results[1]);
  519.       region.viewportAnchorY = Number(results[2]);
  520.     } else if ((results = /^scroll=up$/.exec(word))) {
  521.       region.scroll = shaka.text.CueRegion.scrollMode.UP;
  522.     } else {
  523.       return false;
  524.     }
  526.     return true;
  527.   }
  529.   /**
  530.    * @param {!shaka.text.Cue} cue
  531.    * @param {string} align
  532.    * @private
  533.    */
  534.   static setTextAlign_(cue, align) {
  535.     const Cue = shaka.text.Cue;
  536.     if (align == 'middle') {
  537.       cue.textAlign = Cue.textAlign.CENTER;
  538.     } else {
  539.       goog.asserts.assert(align.toUpperCase() in Cue.textAlign,
  540.           align.toUpperCase() +
  541.                           ' Should be in Cue.textAlign values!');
  543.       cue.textAlign = Cue.textAlign[align.toUpperCase()];
  544.     }
  545.   }
  547.   /**
  548.    * @param {!shaka.text.Cue} cue
  549.    * @param {string} align
  550.    * @private
  551.    */
  552.   static setPositionAlign_(cue, align) {
  553.     const Cue = shaka.text.Cue;
  554.     if (align == 'line-left' || align == 'start') {
  555.       cue.positionAlign = Cue.positionAlign.LEFT;
  556.     } else if (align == 'line-right' || align == 'end') {
  557.       cue.positionAlign = Cue.positionAlign.RIGHT;
  558.     } else if (align == 'center' || align == 'middle') {
  559.       cue.positionAlign = Cue.positionAlign.CENTER;
  560.     } else {
  561.       cue.positionAlign = Cue.positionAlign.AUTO;
  562.     }
  563.   }
  565.   /**
  566.    * @param {!shaka.text.Cue} cue
  567.    * @param {string} value
  568.    * @private
  569.    */
  570.   static setVerticalWritingMode_(cue, value) {
  571.     const Cue = shaka.text.Cue;
  572.     if (value == 'lr') {
  573.       cue.writingMode = Cue.writingMode.VERTICAL_LEFT_TO_RIGHT;
  574.     } else {
  575.       cue.writingMode = Cue.writingMode.VERTICAL_RIGHT_TO_LEFT;
  576.     }
  577.   }
  579.   /**
  580.    * @param {!shaka.text.Cue} cue
  581.    * @param {string} word
  582.    * @return {boolean}
  583.    * @private
  584.    */
  585.   static parsedLineValueAndInterpretation_(cue, word) {
  586.     const Cue = shaka.text.Cue;
  587.     let results = null;
  588.     if ((results = /^line:([\d.]+)%(?:,(start|end|center))?$/.exec(word))) {
  589.       cue.lineInterpretation = Cue.lineInterpretation.PERCENTAGE;
  590.       cue.line = Number(results[1]);
  591.       if (results[2]) {
  592.         goog.asserts.assert(
  593.             results[2].toUpperCase() in Cue.lineAlign,
  594.             results[2].toUpperCase() + ' Should be in Cue.lineAlign values!');
  595.         cue.lineAlign = Cue.lineAlign[results[2].toUpperCase()];
  596.       }
  597.     } else if ((results =
  598.                     /^line:(-?\d+)(?:,(start|end|center))?$/.exec(word))) {
  599.       cue.lineInterpretation = Cue.lineInterpretation.LINE_NUMBER;
  600.       cue.line = Number(results[1]);
  601.       if (results[2]) {
  602.         goog.asserts.assert(
  603.             results[2].toUpperCase() in Cue.lineAlign,
  604.             results[2].toUpperCase() + ' Should be in Cue.lineAlign values!');
  605.         cue.lineAlign = Cue.lineAlign[results[2].toUpperCase()];
  606.       }
  607.     } else {
  608.       return false;
  609.     }
  611.     return true;
  612.   }
  613. };
  615. /**
  616.  * @const {number}
  617.  * @private
  618.  */
  619. shaka.text.VttTextParser.MPEG_TIMESCALE_ = 90000;
  621. /**
  622.  * At this value, timestamps roll over in TS content.
  623.  * @const {number}
  624.  * @private
  625.  */
  626. shaka.text.VttTextParser.TS_ROLLOVER_ = 0x200000000;
  628. shaka.text.TextEngine.registerParser(
  629.     'text/vtt', () => new shaka.text.VttTextParser());
  631. shaka.text.TextEngine.registerParser(
  632.     'text/vtt; codecs="vtt"', () => new shaka.text.VttTextParser());
  634. shaka.text.TextEngine.registerParser(
  635.     'text/vtt; codecs="wvtt"', () => new shaka.text.VttTextParser());