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.     // Only use 'X-TIMESTAMP-MAP' with HLS.  This overrides offset above.
  87.     if (blocks[0].includes('X-TIMESTAMP-MAP') &&
  88.         this.manifestType_ == shaka.media.ManifestParser.HLS) {
  89.       if (this.sequenceMode_) {
  90.         // Compute a different, rollover-based offset for sequence mode.
  91.         offset = this.computeHlsSequenceModeOffset_(blocks[0], time);
  92.       } else {
  93.         // Calculate the offset from the segment startTime.
  94.         offset = time.segmentStart;
  95.       }
  96.     }
  98.     // Parse VTT regions.
  99.     /* !Array.<!shaka.text.CueRegion> */
  100.     const regions = [];
  101.     for (const line of blocks[0].split('\n')) {
  102.       if (/^Region:/.test(line)) {
  103.         const region = VttTextParser.parseRegion_(line);
  104.         regions.push(region);
  105.       }
  106.     }
  108.     /** @type {!Map.<string, !shaka.text.Cue>} */
  109.     const styles = new Map();
  110.     shaka.text.Cue.addDefaultTextColor(styles);
  112.     // Parse cues.
  113.     const ret = [];
  114.     for (const block of blocks.slice(1)) {
  115.       const lines = block.split('\n');
  116.       VttTextParser.parseStyle_(lines, styles);
  117.       const cue = VttTextParser.parseCue_(lines, offset, regions, styles);
  118.       if (cue) {
  119.         ret.push(cue);
  120.       }
  121.     }
  123.     return ret;
  124.   }
  126.   /**
  127.    * @param {string} headerBlock Contains X-TIMESTAMP-MAP.
  128.    * @param {shaka.extern.TextParser.TimeContext} time
  129.    * @return {number}
  130.    * @private
  131.    */
  132.   computeHlsSequenceModeOffset_(headerBlock, time) {
  133.     // https://bit.ly/2K92l7y
  134.     // The 'X-TIMESTAMP-MAP' header is used in HLS to align text with
  135.     // the rest of the media.
  136.     // The header format is 'X-TIMESTAMP-MAP=MPEGTS:n,LOCAL:m'
  137.     // (the attributes can go in any order)
  138.     // where n is MPEG-2 time and m is cue time it maps to.
  139.     // For example 'X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:900000'
  140.     // means an offset of 10 seconds
  141.     // 900000/MPEG_TIMESCALE - cue time.
  142.     const cueTimeMatch = headerBlock.match(
  143.         /LOCAL:((?:(\d{1,}):)?(\d{2}):(\d{2})\.(\d{3}))/m);
  144.     const mpegTimeMatch = headerBlock.match(/MPEGTS:(\d+)/m);
  146.     if (!cueTimeMatch || !mpegTimeMatch) {
  147.       throw new shaka.util.Error(
  148.           shaka.util.Error.Severity.CRITICAL,
  149.           shaka.util.Error.Category.TEXT,
  150.           shaka.util.Error.Code.INVALID_TEXT_HEADER);
  151.     }
  153.     const cueTime = shaka.util.TextParser.parseTime(cueTimeMatch[1]);
  154.     if (cueTime == null) {
  155.       throw new shaka.util.Error(
  156.           shaka.util.Error.Severity.CRITICAL,
  157.           shaka.util.Error.Category.TEXT,
  158.           shaka.util.Error.Code.INVALID_TEXT_HEADER);
  159.     }
  161.     let mpegTime = Number(mpegTimeMatch[1]);
  162.     const mpegTimescale = shaka.text.VttTextParser.MPEG_TIMESCALE_;
  164.     const rolloverSeconds =
  165.         shaka.text.VttTextParser.TS_ROLLOVER_ / mpegTimescale;
  166.     let segmentStart = time.segmentStart - time.periodStart;
  167.     while (segmentStart >= rolloverSeconds) {
  168.       segmentStart -= rolloverSeconds;
  169.       mpegTime += shaka.text.VttTextParser.TS_ROLLOVER_;
  170.     }
  172.     return time.periodStart + mpegTime / mpegTimescale - cueTime;
  173.   }
  175.   /**
  176.    * Parses a string into a Region object.
  177.    *
  178.    * @param {string} text
  179.    * @return {!shaka.text.CueRegion}
  180.    * @private
  181.    */
  182.   static parseRegion_(text) {
  183.     const VttTextParser = shaka.text.VttTextParser;
  184.     const parser = new shaka.util.TextParser(text);
  185.     // The region string looks like this:
  186.     // Region: id=fred width=50% lines=3 regionanchor=0%,100%
  187.     //         viewportanchor=10%,90% scroll=up
  188.     const region = new shaka.text.CueRegion();
  190.     // Skip 'Region:'
  191.     parser.readWord();
  192.     parser.skipWhitespace();
  194.     let word = parser.readWord();
  195.     while (word) {
  196.       if (!VttTextParser.parseRegionSetting_(region, word)) {
  197.         shaka.log.warning(
  198.             'VTT parser encountered an invalid VTTRegion setting: ', word,
  199.             ' The setting will be ignored.');
  200.       }
  201.       parser.skipWhitespace();
  202.       word = parser.readWord();
  203.     }
  205.     return region;
  206.   }
  208.   /**
  209.    * Parses a style block into a Cue object.
  210.    *
  211.    * @param {!Array.<string>} text
  212.    * @param {!Map.<string, !shaka.text.Cue>} styles
  213.    * @private
  214.    */
  215.   static parseStyle_(text, styles) {
  216.     // Skip empty blocks.
  217.     if (text.length == 1 && !text[0]) {
  218.       return;
  219.     }
  221.     // Skip comment blocks.
  222.     if (/^NOTE($|[ \t])/.test(text[0])) {
  223.       return;
  224.     }
  226.     // Only style block are allowed.
  227.     if (text[0] != 'STYLE') {
  228.       return;
  229.     }
  231.     /** @type {!Array.<!Array.<string>>} */
  232.     const styleBlocks = [];
  233.     let lastBlockIndex = -1;
  234.     for (let i = 1; i < text.length; i++) {
  235.       if (text[i].includes('::cue')) {
  236.         styleBlocks.push([]);
  237.         lastBlockIndex = styleBlocks.length - 1;
  238.       }
  239.       if (lastBlockIndex == -1) {
  240.         continue;
  241.       }
  242.       styleBlocks[lastBlockIndex].push(text[i]);
  243.       if (text[i].includes('}')) {
  244.         lastBlockIndex = -1;
  245.       }
  246.     }
  248.     for (const styleBlock of styleBlocks) {
  249.       let styleSelector = 'global';
  250.       // Look for what is within parentheses. For example:
  251.       // <code>:: cue (b) {</code>, what we are looking for is <code>b</code>
  252.       const selector = styleBlock[0].match(/\((.*)\)/);
  253.       if (selector) {
  254.         styleSelector = selector.pop();
  255.       }
  257.       // We start at 1 to avoid '::cue' and end earlier to avoid '}'
  258.       let propertyLines = styleBlock.slice(1, -1);
  259.       if (styleBlock[0].includes('}')) {
  260.         const payload = /\{(.*?)\}/.exec(styleBlock[0]);
  261.         if (payload) {
  262.           propertyLines = payload[1].split(';');
  263.         }
  264.       }
  266.       // Continue styles over multiple selectors if necessary.
  267.       // For example,
  268.       //   ::cue(b) { background: white; } ::cue(b) { color: blue; }
  269.       // should set both the background and foreground of bold tags.
  270.       let cue = styles.get(styleSelector);
  271.       if (!cue) {
  272.         cue = new shaka.text.Cue(0, 0, '');
  273.       }
  275.       let validStyle = false;
  276.       for (let i = 0; i < propertyLines.length; i++) {
  277.         // We look for CSS properties. As a general rule they are separated by
  278.         // <code>:</code>. Eg: <code>color: red;</code>
  279.         const lineParts = /^\s*([^:]+):\s*(.*)/.exec(propertyLines[i]);
  280.         if (lineParts) {
  281.           const name = lineParts[1].trim();
  282.           const value = lineParts[2].trim().replace(';', '');
  283.           switch (name) {
  284.             case 'background-color':
  285.             case 'background':
  286.               validStyle = true;
  287.               cue.backgroundColor = value;
  288.               break;
  289.             case 'color':
  290.               validStyle = true;
  291.               cue.color = value;
  292.               break;
  293.             case 'font-family':
  294.               validStyle = true;
  295.               cue.fontFamily = value;
  296.               break;
  297.             case 'font-size':
  298.               validStyle = true;
  299.               cue.fontSize = value;
  300.               break;
  301.             case 'font-weight':
  302.               if (parseInt(value, 10) >= 700 || value == 'bold') {
  303.                 validStyle = true;
  304.                 cue.fontWeight = shaka.text.Cue.fontWeight.BOLD;
  305.               }
  306.               break;
  307.             case 'font-style':
  308.               switch (value) {
  309.                 case 'normal':
  310.                   validStyle = true;
  311.                   cue.fontStyle = shaka.text.Cue.fontStyle.NORMAL;
  312.                   break;
  313.                 case 'italic':
  314.                   validStyle = true;
  315.                   cue.fontStyle = shaka.text.Cue.fontStyle.ITALIC;
  316.                   break;
  317.                 case 'oblique':
  318.                   validStyle = true;
  319.                   cue.fontStyle = shaka.text.Cue.fontStyle.OBLIQUE;
  320.                   break;
  321.               }
  322.               break;
  323.             case 'opacity':
  324.               validStyle = true;
  325.               cue.opacity = parseFloat(value);
  326.               break;
  327.             case 'text-combine-upright':
  328.               validStyle = true;
  329.               cue.textCombineUpright = value;
  330.               break;
  331.             case 'text-shadow':
  332.               validStyle = true;
  333.               cue.textShadow = value;
  334.               break;
  335.             case 'white-space':
  336.               validStyle = true;
  337.               cue.wrapLine = value != 'noWrap';
  338.               break;
  339.             default:
  340.               shaka.log.warning('VTT parser encountered an unsupported style: ',
  341.                   lineParts);
  342.               break;
  343.           }
  344.         }
  345.       }
  347.       if (validStyle) {
  348.         styles.set(styleSelector, cue);
  349.       }
  350.     }
  351.   }
  353.   /**
  354.    * Parses a text block into a Cue object.
  355.    *
  356.    * @param {!Array.<string>} text
  357.    * @param {number} timeOffset
  358.    * @param {!Array.<!shaka.text.CueRegion>} regions
  359.    * @param {!Map.<string, !shaka.text.Cue>} styles
  360.    * @return {shaka.text.Cue}
  361.    * @private
  362.    */
  363.   static parseCue_(text, timeOffset, regions, styles) {
  364.     const VttTextParser = shaka.text.VttTextParser;
  366.     // Skip empty blocks.
  367.     if (text.length == 1 && !text[0]) {
  368.       return null;
  369.     }
  371.     // Skip comment blocks.
  372.     if (/^NOTE($|[ \t])/.test(text[0])) {
  373.       return null;
  374.     }
  376.     // Skip style and region blocks.
  377.     if (text[0] == 'STYLE' || text[0] == 'REGION') {
  378.       return null;
  379.     }
  381.     let id = null;
  382.     if (!text[0].includes('-->')) {
  383.       id = text[0];
  384.       text.splice(0, 1);
  385.     }
  387.     // Parse the times.
  388.     const parser = new shaka.util.TextParser(text[0]);
  389.     let start = parser.parseTime();
  390.     const expect = parser.readRegex(/[ \t]+-->[ \t]+/g);
  391.     let end = parser.parseTime();
  393.     if (start == null || expect == null || end == null) {
  394.       shaka.log.alwaysWarn(
  395.           'Failed to parse VTT time code. Cue skipped:', id, text);
  396.       return null;
  397.     }
  399.     start += timeOffset;
  400.     end += timeOffset;
  402.     // Get the payload.
  403.     const payload = text.slice(1).join('\n').trim();
  405.     let cue = null;
  406.     if (styles.has('global')) {
  407.       cue = styles.get('global').clone();
  408.       cue.startTime = start;
  409.       cue.endTime = end;
  410.       cue.payload = payload;
  411.     } else {
  412.       cue = new shaka.text.Cue(start, end, payload);
  413.     }
  415.     // Parse optional settings.
  416.     parser.skipWhitespace();
  417.     let word = parser.readWord();
  418.     while (word) {
  419.       if (!VttTextParser.parseCueSetting(cue, word, regions)) {
  420.         shaka.log.warning('VTT parser encountered an invalid VTT setting: ',
  421.             word,
  422.             ' The setting will be ignored.');
  423.       }
  424.       parser.skipWhitespace();
  425.       word = parser.readWord();
  426.     }
  428.     shaka.text.Cue.parseCuePayload(cue, styles);
  430.     if (id != null) {
  431.       cue.id = id;
  432.     }
  433.     return cue;
  434.   }
  436.   /**
  437.    * Parses a WebVTT setting from the given word.
  438.    *
  439.    * @param {!shaka.text.Cue} cue
  440.    * @param {string} word
  441.    * @param {!Array.<!shaka.text.CueRegion>} regions
  442.    * @return {boolean} True on success.
  443.    */
  444.   static parseCueSetting(cue, word, regions) {
  445.     const VttTextParser = shaka.text.VttTextParser;
  446.     let results = null;
  447.     if ((results = /^align:(start|middle|center|end|left|right)$/.exec(word))) {
  448.       VttTextParser.setTextAlign_(cue, results[1]);
  449.     } else if ((results = /^vertical:(lr|rl)$/.exec(word))) {
  450.       VttTextParser.setVerticalWritingMode_(cue, results[1]);
  451.     } else if ((results = /^size:([\d.]+)%$/.exec(word))) {
  452.       cue.size = Number(results[1]);
  453.     } else if ((results =
  454.         // eslint-disable-next-line max-len
  455.         /^position:([\d.]+)%(?:,(line-left|line-right|middle|center|start|end|auto))?$/
  456.             .exec(word))) {
  457.       cue.position = Number(results[1]);
  458.       if (results[2]) {
  459.         VttTextParser.setPositionAlign_(cue, results[2]);
  460.       }
  461.     } else if ((results = /^region:(.*)$/.exec(word))) {
  462.       const region = VttTextParser.getRegionById_(regions, results[1]);
  463.       if (region) {
  464.         cue.region = region;
  465.       }
  466.     } else {
  467.       return VttTextParser.parsedLineValueAndInterpretation_(cue, word);
  468.     }
  470.     return true;
  471.   }
  473.   /**
  474.    *
  475.    * @param {!Array.<!shaka.text.CueRegion>} regions
  476.    * @param {string} id
  477.    * @return {?shaka.text.CueRegion}
  478.    * @private
  479.    */
  480.   static getRegionById_(regions, id) {
  481.     const regionsWithId = regions.filter((region) => {
  482.       return region.id == id;
  483.     });
  484.     if (!regionsWithId.length) {
  485.       shaka.log.warning('VTT parser could not find a region with id: ',
  486.           id,
  487.           ' The region will be ignored.');
  488.       return null;
  489.     }
  490.     goog.asserts.assert(regionsWithId.length == 1,
  491.         'VTTRegion ids should be unique!');
  493.     return regionsWithId[0];
  494.   }
  496.   /**
  497.    * Parses a WebVTTRegion setting from the given word.
  498.    *
  499.    * @param {!shaka.text.CueRegion} region
  500.    * @param {string} word
  501.    * @return {boolean} True on success.
  502.    * @private
  503.    */
  504.   static parseRegionSetting_(region, word) {
  505.     let results = null;
  506.     if ((results = /^id=(.*)$/.exec(word))) {
  507.       region.id = results[1];
  508.     } else if ((results = /^width=(\d{1,2}|100)%$/.exec(word))) {
  509.       region.width = Number(results[1]);
  510.     } else if ((results = /^lines=(\d+)$/.exec(word))) {
  511.       region.height = Number(results[1]);
  512.       region.heightUnits = shaka.text.CueRegion.units.LINES;
  513.     } else if ((results = /^regionanchor=(\d{1,2}|100)%,(\d{1,2}|100)%$/
  514.         .exec(word))) {
  515.       region.regionAnchorX = Number(results[1]);
  516.       region.regionAnchorY = Number(results[2]);
  517.     } else if ((results = /^viewportanchor=(\d{1,2}|100)%,(\d{1,2}|100)%$/
  518.         .exec(word))) {
  519.       region.viewportAnchorX = Number(results[1]);
  520.       region.viewportAnchorY = Number(results[2]);
  521.     } else if ((results = /^scroll=up$/.exec(word))) {
  522.       region.scroll = shaka.text.CueRegion.scrollMode.UP;
  523.     } else {
  524.       return false;
  525.     }
  527.     return true;
  528.   }
  530.   /**
  531.    * @param {!shaka.text.Cue} cue
  532.    * @param {string} align
  533.    * @private
  534.    */
  535.   static setTextAlign_(cue, align) {
  536.     const Cue = shaka.text.Cue;
  537.     if (align == 'middle') {
  538.       cue.textAlign = Cue.textAlign.CENTER;
  539.     } else {
  540.       goog.asserts.assert(align.toUpperCase() in Cue.textAlign,
  541.           align.toUpperCase() +
  542.                           ' Should be in Cue.textAlign values!');
  544.       cue.textAlign = Cue.textAlign[align.toUpperCase()];
  545.     }
  546.   }
  548.   /**
  549.    * @param {!shaka.text.Cue} cue
  550.    * @param {string} align
  551.    * @private
  552.    */
  553.   static setPositionAlign_(cue, align) {
  554.     const Cue = shaka.text.Cue;
  555.     if (align == 'line-left' || align == 'start') {
  556.       cue.positionAlign = Cue.positionAlign.LEFT;
  557.     } else if (align == 'line-right' || align == 'end') {
  558.       cue.positionAlign = Cue.positionAlign.RIGHT;
  559.     } else if (align == 'center' || align == 'middle') {
  560.       cue.positionAlign = Cue.positionAlign.CENTER;
  561.     } else {
  562.       cue.positionAlign = Cue.positionAlign.AUTO;
  563.     }
  564.   }
  566.   /**
  567.    * @param {!shaka.text.Cue} cue
  568.    * @param {string} value
  569.    * @private
  570.    */
  571.   static setVerticalWritingMode_(cue, value) {
  572.     const Cue = shaka.text.Cue;
  573.     if (value == 'lr') {
  574.       cue.writingMode = Cue.writingMode.VERTICAL_LEFT_TO_RIGHT;
  575.     } else {
  576.       cue.writingMode = Cue.writingMode.VERTICAL_RIGHT_TO_LEFT;
  577.     }
  578.   }
  580.   /**
  581.    * @param {!shaka.text.Cue} cue
  582.    * @param {string} word
  583.    * @return {boolean}
  584.    * @private
  585.    */
  586.   static parsedLineValueAndInterpretation_(cue, word) {
  587.     const Cue = shaka.text.Cue;
  588.     let results = null;
  589.     if ((results = /^line:([\d.]+)%(?:,(start|end|center))?$/.exec(word))) {
  590.       cue.lineInterpretation = Cue.lineInterpretation.PERCENTAGE;
  591.       cue.line = Number(results[1]);
  592.       if (results[2]) {
  593.         goog.asserts.assert(
  594.             results[2].toUpperCase() in Cue.lineAlign,
  595.             results[2].toUpperCase() + ' Should be in Cue.lineAlign values!');
  596.         cue.lineAlign = Cue.lineAlign[results[2].toUpperCase()];
  597.       }
  598.     } else if ((results =
  599.                     /^line:(-?\d+)(?:,(start|end|center))?$/.exec(word))) {
  600.       cue.lineInterpretation = Cue.lineInterpretation.LINE_NUMBER;
  601.       cue.line = Number(results[1]);
  602.       if (results[2]) {
  603.         goog.asserts.assert(
  604.             results[2].toUpperCase() in Cue.lineAlign,
  605.             results[2].toUpperCase() + ' Should be in Cue.lineAlign values!');
  606.         cue.lineAlign = Cue.lineAlign[results[2].toUpperCase()];
  607.       }
  608.     } else {
  609.       return false;
  610.     }
  612.     return true;
  613.   }
  614. };
  616. /**
  617.  * @const {number}
  618.  * @private
  619.  */
  620. shaka.text.VttTextParser.MPEG_TIMESCALE_ = 90000;
  622. /**
  623.  * At this value, timestamps roll over in TS content.
  624.  * @const {number}
  625.  * @private
  626.  */
  627. shaka.text.VttTextParser.TS_ROLLOVER_ = 0x200000000;
  629. shaka.text.TextEngine.registerParser(
  630.     'text/vtt', () => new shaka.text.VttTextParser());
  632. shaka.text.TextEngine.registerParser(
  633.     'text/vtt; codecs="vtt"', () => new shaka.text.VttTextParser());
  635. shaka.text.TextEngine.registerParser(
  636.     'text/vtt; codecs="wvtt"', () => new shaka.text.VttTextParser());