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.       mimeType: null,
  144.       pictureType: null,
  145.     };
  147.     if (frame.type === 'APIC') {
  148.       /*
  149.        * Format:
  150.        * [0]       = {Text Encoding}
  151.        * [1 - X]   = {MIME Type}\0
  152.        * [X+1]     = {Picture Type}
  153.        * [X+2 - Y] = {Description}\0
  154.        * [Y - ?]   = {Picture Data or Picture URL}
  155.        */
  156.       if (frame.size < 2) {
  157.         return null;
  158.       }
  159.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  160.         shaka.log.warning('Ignore frame with unrecognized character ' +
  161.             'encoding');
  162.         return null;
  163.       }
  165.       const mimeTypeEndIndex = frame.data.subarray(1).indexOf(0);
  166.       if (mimeTypeEndIndex === -1) {
  167.         return null;
  168.       }
  169.       const mimeType = StringUtils.fromUTF8(
  170.           BufferUtils.toUint8(frame.data, 1, mimeTypeEndIndex));
  171.       const pictureType = frame.data[2 + mimeTypeEndIndex];
  172.       const descriptionEndIndex = frame.data.subarray(3 + mimeTypeEndIndex)
  173.           .indexOf(0);
  174.       if (descriptionEndIndex === -1) {
  175.         return null;
  176.       }
  177.       const description = StringUtils.fromUTF8(
  178.           BufferUtils.toUint8(frame.data, 3 + mimeTypeEndIndex,
  179.               descriptionEndIndex));
  180.       let data;
  181.       if (mimeType === '-->') {
  182.         data = StringUtils.fromUTF8(
  183.             BufferUtils.toUint8(
  184.                 frame.data, 4 + mimeTypeEndIndex + descriptionEndIndex));
  185.       } else {
  186.         data = BufferUtils.toArrayBuffer(
  187.             frame.data.subarray(4 + mimeTypeEndIndex + descriptionEndIndex));
  188.       }
  189.       metadataFrame.mimeType = mimeType;
  190.       metadataFrame.pictureType = pictureType;
  191.       metadataFrame.description = description;
  192.       metadataFrame.data = data;
  193.       return metadataFrame;
  194.     } else if (frame.type === 'TXXX') {
  195.       /*
  196.        * Format:
  197.        * [0]   = {Text Encoding}
  198.        * [1-?] = {Description}\0{Value}
  199.        */
  200.       if (frame.size < 2) {
  201.         return null;
  202.       }
  203.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  204.         shaka.log.warning('Ignore frame with unrecognized character ' +
  205.             'encoding');
  206.         return null;
  207.       }
  208.       const descriptionEndIndex = frame.data.subarray(1).indexOf(0);
  210.       if (descriptionEndIndex === -1) {
  211.         return null;
  212.       }
  213.       const description = StringUtils.fromUTF8(
  214.           BufferUtils.toUint8(frame.data, 1, descriptionEndIndex));
  215.       const data = StringUtils.fromUTF8(
  216.           BufferUtils.toUint8(frame.data, 2 + descriptionEndIndex))
  217.           .replace(/\0*$/, '');
  219.       metadataFrame.description = description;
  220.       metadataFrame.data = data;
  221.       return metadataFrame;
  222.     } else if (frame.type === 'WXXX') {
  223.       /*
  224.        * Format:
  225.        * [0]   = {Text Encoding}
  226.        * [1-?] = {Description}\0{URL}
  227.        */
  228.       if (frame.size < 2) {
  229.         return null;
  230.       }
  231.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  232.         shaka.log.warning('Ignore frame with unrecognized character ' +
  233.             'encoding');
  234.         return null;
  235.       }
  236.       const descriptionEndIndex = frame.data.subarray(1).indexOf(0);
  238.       if (descriptionEndIndex === -1) {
  239.         return null;
  240.       }
  241.       const description = StringUtils.fromUTF8(
  242.           BufferUtils.toUint8(frame.data, 1, descriptionEndIndex));
  243.       const data = StringUtils.fromUTF8(
  244.           BufferUtils.toUint8(frame.data, 2 + descriptionEndIndex))
  245.           .replace(/\0*$/, '');
  247.       metadataFrame.description = description;
  248.       metadataFrame.data = data;
  249.       return metadataFrame;
  250.     } else if (frame.type === 'PRIV') {
  251.       /*
  252.        * Format: <text string>\0<binary data>
  253.        */
  254.       if (frame.size < 2) {
  255.         return null;
  256.       }
  257.       const textEndIndex = frame.data.indexOf(0);
  258.       if (textEndIndex === -1) {
  259.         return null;
  260.       }
  261.       const text = StringUtils.fromUTF8(
  262.           BufferUtils.toUint8(frame.data, 0, textEndIndex));
  263.       metadataFrame.description = text;
  264.       if (text == 'com.apple.streaming.transportStreamTimestamp') {
  265.         const data = frame.data.subarray(text.length + 1);
  266.         // timestamp is 33 bit expressed as a big-endian eight-octet number,
  267.         // with the upper 31 bits set to zero.
  268.         const pts33Bit = data[3] & 0x1;
  269.         let timestamp =
  270.           (data[4] << 23) + (data[5] << 15) + (data[6] << 7) + data[7];
  271.         timestamp /= 45;
  273.         if (pts33Bit) {
  274.           timestamp += 47721858.84;
  275.         } // 2^32 / 90
  277.         metadataFrame.data = timestamp;
  278.       } else {
  279.         const data = BufferUtils.toArrayBuffer(
  280.             frame.data.subarray(text.length + 1));
  281.         metadataFrame.data = data;
  282.       }
  283.       return metadataFrame;
  284.     } else if (frame.type[0] === 'T') {
  285.       /*
  286.        * Format:
  287.        * [0]   = {Text Encoding}
  288.        * [1-?] = {Value}
  289.        */
  290.       if (frame.size < 2) {
  291.         return null;
  292.       }
  293.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  294.         shaka.log.warning('Ignore frame with unrecognized character ' +
  295.             'encoding');
  296.         return null;
  297.       }
  298.       const text = StringUtils.fromUTF8(frame.data.subarray(1))
  299.           .replace(/\0*$/, '');
  300.       metadataFrame.data = text;
  301.       return metadataFrame;
  302.     } else if (frame.type[0] === 'W') {
  303.       /*
  304.        * Format:
  305.        * [0-?] = {URL}
  306.        */
  307.       const url = StringUtils.fromUTF8(frame.data)
  308.           .replace(/\0*$/, '');
  309.       metadataFrame.data = url;
  310.       return metadataFrame;
  311.     } else if (frame.data) {
  312.       shaka.log.warning('Unrecognized ID3 frame type:', frame.type);
  313.       metadataFrame.data = BufferUtils.toArrayBuffer(frame.data);
  314.       return metadataFrame;
  315.     }
  317.     return null;
  318.   }
  320.   /**
  321.    * Returns an array of ID3 frames found in all the ID3 tags in the id3Data
  322.    * @param {Uint8Array} id3Data - The ID3 data containing one or more ID3 tags
  323.    * @return {!Array<shaka.extern.MetadataFrame>}
  324.    * @export
  325.    */
  326.   static getID3Frames(id3Data) {
  327.     const Id3Utils = shaka.util.Id3Utils;
  328.     let offset = 0;
  329.     const frames = [];
  330.     while (Id3Utils.isHeader_(id3Data, offset)) {
  331.       const size = Id3Utils.readSize_(id3Data, offset + 6);
  333.       if ((id3Data[offset + 5] >> 6) & 1) {
  334.         // skip extended header
  335.         offset += 10;
  336.       }
  337.       // skip past ID3 header
  338.       offset += 10;
  340.       const end = offset + size;
  341.       // loop through frames in the ID3 tag
  342.       while (offset + 10 < end) {
  343.         const frameData = Id3Utils.getFrameData_(id3Data.subarray(offset));
  344.         const frame = Id3Utils.decodeFrame_(frameData);
  345.         if (frame) {
  346.           frames.push(frame);
  347.         }
  349.         // skip frame header and frame data
  350.         offset += frameData.size + 10;
  351.       }
  353.       if (Id3Utils.isFooter_(id3Data, offset)) {
  354.         offset += 10;
  355.       }
  356.     }
  357.     return frames;
  358.   }
  360.   /**
  361.    * Returns any adjacent ID3 tags found in data starting at offset, as one
  362.    * block of data
  363.    * @param {Uint8Array} id3Data - The ID3 data containing one or more ID3 tags
  364.    * @param {number=} offset - The offset at which to start searching
  365.    * @return {!Uint8Array}
  366.    * @export
  367.    */
  368.   static getID3Data(id3Data, offset = 0) {
  369.     const Id3Utils = shaka.util.Id3Utils;
  370.     const front = offset;
  371.     let length = 0;
  373.     while (Id3Utils.isHeader_(id3Data, offset)) {
  374.       if ((id3Data[offset + 5] >> 6) & 1) {
  375.         // skip extended header
  376.         length += 10;
  377.       }
  378.       // skip past ID3 header
  379.       length += 10;
  381.       const size = Id3Utils.readSize_(id3Data, offset + 6);
  382.       length += size;
  384.       if (Id3Utils.isFooter_(id3Data, offset + 10)) {
  385.         // ID3 footer is 10 bytes
  386.         length += 10;
  387.       }
  388.       offset += length;
  389.     }
  391.     if (length > 0) {
  392.       return id3Data.subarray(front, front + length);
  393.     }
  394.     return new Uint8Array([]);
  395.   }
  396. };
  398. /**
  399.  * UTF8 encoding byte
  400.  * @const {number}
  401.  */
  402. shaka.util.Id3Utils.UTF8_encoding = 0x03;