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.       const data = BufferUtils.toArrayBuffer(
  215.           frame.data.subarray(text.length + 1));
  216.       metadataFrame.description = text;
  217.       metadataFrame.data = data;
  218.       return metadataFrame;
  219.     } else if (frame.type[0] === 'T') {
  220.       /*
  221.        * Format:
  222.        * [0]   = {Text Encoding}
  223.        * [1-?] = {Value}
  224.        */
  225.       if (frame.size < 2) {
  226.         return null;
  227.       }
  228.       if (frame.data[0] !== shaka.util.Id3Utils.UTF8_encoding) {
  229.         shaka.log.warning('Ignore frame with unrecognized character ' +
  230.             'encoding');
  231.         return null;
  232.       }
  233.       const text = StringUtils.fromUTF8(frame.data.subarray(1))
  234.           .replace(/\0*$/, '');
  235.       metadataFrame.data = text;
  236.       return metadataFrame;
  237.     } else if (frame.type[0] === 'W') {
  238.       /*
  239.        * Format:
  240.        * [0-?] = {URL}
  241.        */
  242.       const url = StringUtils.fromUTF8(frame.data)
  243.           .replace(/\0*$/, '');
  244.       metadataFrame.data = url;
  245.       return metadataFrame;
  246.     } else if (frame.data) {
  247.       shaka.log.warning('Unrecognized ID3 frame type:', frame.type);
  248.       metadataFrame.data = BufferUtils.toArrayBuffer(frame.data);
  249.       return metadataFrame;
  250.     }
  252.     return null;
  253.   }
  255.   /**
  256.    * Returns an array of ID3 frames found in all the ID3 tags in the id3Data
  257.    * @param {Uint8Array} id3Data - The ID3 data containing one or more ID3 tags
  258.    * @return {!Array.<shaka.extern.MetadataFrame>}
  259.    * @export
  260.    */
  261.   static getID3Frames(id3Data) {
  262.     const Id3Utils = shaka.util.Id3Utils;
  263.     let offset = 0;
  264.     const frames = [];
  265.     while (Id3Utils.isHeader_(id3Data, offset)) {
  266.       const size = Id3Utils.readSize_(id3Data, offset + 6);
  268.       if ((id3Data[offset + 5] >> 6) & 1) {
  269.         // skip extended header
  270.         offset += 10;
  271.       }
  272.       // skip past ID3 header
  273.       offset += 10;
  275.       const end = offset + size;
  276.       // loop through frames in the ID3 tag
  277.       while (offset + 10 < end) {
  278.         const frameData = Id3Utils.getFrameData_(id3Data.subarray(offset));
  279.         const frame = Id3Utils.decodeFrame_(frameData);
  280.         if (frame) {
  281.           frames.push(frame);
  282.         }
  284.         // skip frame header and frame data
  285.         offset += frameData.size + 10;
  286.       }
  288.       if (Id3Utils.isFooter_(id3Data, offset)) {
  289.         offset += 10;
  290.       }
  291.     }
  292.     return frames;
  293.   }
  294. };
  296. /**
  297.  * UTF8 encoding byte
  298.  * @const {number}
  299.  */
  300. shaka.util.Id3Utils.UTF8_encoding = 0x03;