Source: lib/util/id3_utils.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2022 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.Id3Utils');
  9. goog.require('shaka.log');
  10. goog.require('shaka.util.BufferUtils');
  11. goog.require('shaka.util.StringUtils');
  14. /**
  15.  * @summary A set of Id3Utils utility functions.
  16.  * @export
  17.  */
  18. shaka.util.Id3Utils = class {
  19.   /**
  20.    * @param {Uint8Array} data
  21.    * @param {number} offset
  22.    * @return {boolean}
  23.    * @private
  24.    */
  25.   static isHeader_(data, offset) {
  26.     /*
  27.      * http://id3.org/id3v2.3.0
  28.      * [0]     = 'I'
  29.      * [1]     = 'D'
  30.      * [2]     = '3'
  31.      * [3,4]   = {Version}
  32.      * [5]     = {Flags}
  33.      * [6-9]   = {ID3 Size}
  34.      *
  35.      * An ID3v2 tag can be detected with the following pattern:
  36.      *  $49 44 33 yy yy xx zz zz zz zz
  37.      * Where yy is less than $FF, xx is the 'flags' byte and zz is less than $80
  38.      */
  39.     if (offset + 10 <= data.length) {
  40.       // look for 'ID3' identifier
  41.       if (data[offset] === 0x49 &&
  42.           data[offset + 1] === 0x44 &&
  43.           data[offset + 2] === 0x33) {
  44.         // check version is within range
  45.         if (data[offset + 3] < 0xff && data[offset + 4] < 0xff) {
  46.           // check size is within range
  47.           if (data[offset + 6] < 0x80 &&
  48.               data[offset + 7] < 0x80 &&
  49.               data[offset + 8] < 0x80 &&
  50.               data[offset + 9] < 0x80) {
  51.             return true;
  52.           }
  53.         }
  54.       }
  55.     }
  57.     return false;
  58.   }
  60.   /**
  61.    * @param {Uint8Array} data
  62.    * @param {number} offset
  63.    * @return {boolean}
  64.    * @private
  65.    */
  66.   static isFooter_(data, offset) {
  67.     /*
  68.      * The footer is a copy of the header, but with a different identifier
  69.      */
  70.     if (offset + 10 <= data.length) {
  71.       // look for '3DI' identifier
  72.       if (data[offset] === 0x33 &&
  73.           data[offset + 1] === 0x44 &&
  74.           data[offset + 2] === 0x49) {
  75.         // check version is within range
  76.         if (data[offset + 3] < 0xff && data[offset + 4] < 0xff) {
  77.           // check size is within range
  78.           if (data[offset + 6] < 0x80 &&
  79.               data[offset + 7] < 0x80 &&
  80.               data[offset + 8] < 0x80 &&
  81.               data[offset + 9] < 0x80) {
  82.             return true;
  83.           }
  84.         }
  85.       }
  86.     }
  88.     return false;
  89.   }
  91.   /**
  92.    * @param {Uint8Array} data
  93.    * @param {number} offset
  94.    * @return {number}
  95.    * @private
  96.    */
  97.   static readSize_(data, offset) {
  98.     let size = 0;
  99.     size = (data[offset] & 0x7f) << 21;
  100.     size |= (data[offset + 1] & 0x7f) << 14;
  101.     size |= (data[offset + 2] & 0x7f) << 7;
  102.     size |= data[offset + 3] & 0x7f;
  103.     return size;
  104.   }
  106.   /**
  107.    * @param {Uint8Array} data
  108.    * @return {shaka.extern.MetadataRawFrame}
  109.    * @private
  110.    */
  111.   static getFrameData_(data) {
  112.     /*
  113.      * Frame ID       $xx xx xx xx (four characters)
  114.      * Size           $xx xx xx xx
  115.      * Flags          $xx xx
  116.      */
  117.     const type = String.fromCharCode(data[0], data[1], data[2], data[3]);
  118.     const size = shaka.util.Id3Utils.readSize_(data, 4);
  120.     // skip frame id, size, and flags
  121.     const offset = 10;
  123.     return {
  124.       type,
  125.       size,
  126.       data: data.subarray(offset, offset + size),
  127.     };
  128.   }
  130.   /**
  131.    * @param {shaka.extern.MetadataRawFrame} frame
  132.    * @return {?shaka.extern.MetadataFrame}
  133.    * @private
  134.    */
  135.   static decodeFrame_(frame) {
  136.     const BufferUtils = shaka.util.BufferUtils;
  137.     const StringUtils = shaka.util.StringUtils;
  139.     const metadataFrame = {
  140.       key: frame.type,
  141.       description: '',
  142.       data: '',
  143.     };
  145.     if (frame.type === 'TXXX') {
  146.       /*
  147.        * Format:
  148.        * [0]   = {Text Encoding}
  149.        * [1-?] = {Description}\0{Value}
  150.        */
  151.       if (frame.size < 2) {
  152.         return null;
  153.       }
  154.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  155.         shaka.log.warning('Ignore frame with unrecognized character ' +
  156.             'encoding');
  157.         return null;
  158.       }
  159.       const descriptionEndIndex = frame.data.subarray(1).indexOf(0);
  161.       if (descriptionEndIndex === -1) {
  162.         return null;
  163.       }
  164.       const description = StringUtils.fromUTF8(
  165.           BufferUtils.toUint8(frame.data, 1, descriptionEndIndex));
  166.       const data = StringUtils.fromUTF8(
  167.           BufferUtils.toUint8(frame.data, 2 + descriptionEndIndex))
  168.           .replace(/\0*$/, '');
  170.       metadataFrame.description = description;
  171.       metadataFrame.data = data;
  172.       return metadataFrame;
  173.     } else if (frame.type === 'WXXX') {
  174.       /*
  175.        * Format:
  176.        * [0]   = {Text Encoding}
  177.        * [1-?] = {Description}\0{URL}
  178.        */
  179.       if (frame.size < 2) {
  180.         return null;
  181.       }
  182.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  183.         shaka.log.warning('Ignore frame with unrecognized character ' +
  184.             'encoding');
  185.         return null;
  186.       }
  187.       const descriptionEndIndex = frame.data.subarray(1).indexOf(0);
  189.       if (descriptionEndIndex === -1) {
  190.         return null;
  191.       }
  192.       const description = StringUtils.fromUTF8(
  193.           BufferUtils.toUint8(frame.data, 1, descriptionEndIndex));
  194.       const data = StringUtils.fromUTF8(
  195.           BufferUtils.toUint8(frame.data, 2 + descriptionEndIndex))
  196.           .replace(/\0*$/, '');
  198.       metadataFrame.description = description;
  199.       metadataFrame.data = data;
  200.       return metadataFrame;
  201.     } else if (frame.type === 'PRIV') {
  202.       /*
  203.        * Format: <text string>\0<binary data>
  204.        */
  205.       if (frame.size < 2) {
  206.         return null;
  207.       }
  208.       const textEndIndex = frame.data.indexOf(0);
  209.       if (textEndIndex === -1) {
  210.         return null;
  211.       }
  212.       const text = StringUtils.fromUTF8(
  213.           BufferUtils.toUint8(frame.data, 0, textEndIndex));
  214.       metadataFrame.description = text;
  215.       if (text == 'com.apple.streaming.transportStreamTimestamp') {
  216.         const data = frame.data.subarray(text.length + 1);
  217.         // timestamp is 33 bit expressed as a big-endian eight-octet number,
  218.         // with the upper 31 bits set to zero.
  219.         const pts33Bit = data[3] & 0x1;
  220.         let timestamp =
  221.           (data[4] << 23) + (data[5] << 15) + (data[6] << 7) + data[7];
  222.         timestamp /= 45;
  224.         if (pts33Bit) {
  225.           timestamp += 47721858.84;
  226.         } // 2^32 / 90
  228.         metadataFrame.data = timestamp;
  229.       } else {
  230.         const data = BufferUtils.toArrayBuffer(
  231.             frame.data.subarray(text.length + 1));
  232.         metadataFrame.data = data;
  233.       }
  234.       return metadataFrame;
  235.     } else if (frame.type[0] === 'T') {
  236.       /*
  237.        * Format:
  238.        * [0]   = {Text Encoding}
  239.        * [1-?] = {Value}
  240.        */
  241.       if (frame.size < 2) {
  242.         return null;
  243.       }
  244.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  245.         shaka.log.warning('Ignore frame with unrecognized character ' +
  246.             'encoding');
  247.         return null;
  248.       }
  249.       const text = StringUtils.fromUTF8(frame.data.subarray(1))
  250.           .replace(/\0*$/, '');
  251.       metadataFrame.data = text;
  252.       return metadataFrame;
  253.     } else if (frame.type[0] === 'W') {
  254.       /*
  255.        * Format:
  256.        * [0-?] = {URL}
  257.        */
  258.       const url = StringUtils.fromUTF8(frame.data)
  259.           .replace(/\0*$/, '');
  260.       metadataFrame.data = url;
  261.       return metadataFrame;
  262.     } else if (frame.data) {
  263.       shaka.log.warning('Unrecognized ID3 frame type:', frame.type);
  264.       metadataFrame.data = BufferUtils.toArrayBuffer(frame.data);
  265.       return metadataFrame;
  266.     }
  268.     return null;
  269.   }
  271.   /**
  272.    * Returns an array of ID3 frames found in all the ID3 tags in the id3Data
  273.    * @param {Uint8Array} id3Data - The ID3 data containing one or more ID3 tags
  274.    * @return {!Array.<shaka.extern.MetadataFrame>}
  275.    * @export
  276.    */
  277.   static getID3Frames(id3Data) {
  278.     const Id3Utils = shaka.util.Id3Utils;
  279.     let offset = 0;
  280.     const frames = [];
  281.     while (Id3Utils.isHeader_(id3Data, offset)) {
  282.       const size = Id3Utils.readSize_(id3Data, offset + 6);
  284.       if ((id3Data[offset + 5] >> 6) & 1) {
  285.         // skip extended header
  286.         offset += 10;
  287.       }
  288.       // skip past ID3 header
  289.       offset += 10;
  291.       const end = offset + size;
  292.       // loop through frames in the ID3 tag
  293.       while (offset + 10 < end) {
  294.         const frameData = Id3Utils.getFrameData_(id3Data.subarray(offset));
  295.         const frame = Id3Utils.decodeFrame_(frameData);
  296.         if (frame) {
  297.           frames.push(frame);
  298.         }
  300.         // skip frame header and frame data
  301.         offset += frameData.size + 10;
  302.       }
  304.       if (Id3Utils.isFooter_(id3Data, offset)) {
  305.         offset += 10;
  306.       }
  307.     }
  308.     return frames;
  309.   }
  311.   /**
  312.    * Returns any adjacent ID3 tags found in data starting at offset, as one
  313.    * block of data
  314.    * @param {Uint8Array} id3Data - The ID3 data containing one or more ID3 tags
  315.    * @param {number=} offset - The offset at which to start searching
  316.    * @return {!Uint8Array}
  317.    * @export
  318.    */
  319.   static getID3Data(id3Data, offset = 0) {
  320.     const Id3Utils = shaka.util.Id3Utils;
  321.     const front = offset;
  322.     let length = 0;
  324.     while (Id3Utils.isHeader_(id3Data, offset)) {
  325.       if ((id3Data[offset + 5] >> 6) & 1) {
  326.         // skip extended header
  327.         length += 10;
  328.       }
  329.       // skip past ID3 header
  330.       length += 10;
  332.       const size = Id3Utils.readSize_(id3Data, offset + 6);
  333.       length += size;
  335.       if (Id3Utils.isFooter_(id3Data, offset + 10)) {
  336.         // ID3 footer is 10 bytes
  337.         length += 10;
  338.       }
  339.       offset += length;
  340.     }
  342.     if (length > 0) {
  343.       return id3Data.subarray(front, front + length);
  344.     }
  345.     return new Uint8Array([]);
  346.   }
  347. };
  349. /**
  350.  * UTF8 encoding byte
  351.  * @const {number}
  352.  */
  353. shaka.util.Id3Utils.UTF8_encoding = 0x03;