music-metadata 11.15.0 → 11.16.0

package/README.md

@@ -84,7 +84,7 @@ Following tag header formats are supported:
 Following lyric formats are supported:
 - [LRC](https://en.wikipedia.org/wiki/LRC_(file_format))
 - Synchronized lyrics (SYLT)
-- Unsynchronized lyrics (USULT)
+- Unsynchronized lyrics (USLT)
 
 Support for [MusicBrainz](https://musicbrainz.org/) tags as written by [Picard](https://picard.musicbrainz.org/).
 [ReplayGain](https://wiki.hydrogenaud.io/index.php?title=ReplayGain) tags are supported.
@@ -123,7 +123,7 @@ yarn add music-metadata
 
 **Node.js specific** functions to read an audio file or stream:
 1. **File Parsing**: Parse audio files directly from the filesystem using the [parseFile function](#parsefile-function)
-1. **Stream Parsing**: Parse audio metadata from a Node.js [Readable stream](https://nodejs.org/api/stream.html#class-streamreadable) using the [parseStream function](#parsewebstream-function).
+1. **Stream Parsing**: Parse audio metadata from a Node.js [Readable stream](https://nodejs.org/api/stream.html#class-streamreadable) using the [parseStream function](#parsestream-function).
 
 **Cross-platform** functions available to read an audio file or stream:
 
@@ -136,8 +136,8 @@ There are multiple ways to parse (read) audio tracks:
 > [!NOTE]
 > Direct file access in Node.js is generally faster because it can 'jump' to various parts of the file without reading intermediate data.
 
-### Node.js specific function
-These functions are tailored for Node.js environments and leverage Node.js-specific APIs,
+### Node.js specific functions
+These functions use Node.js-specific APIs,
 making them incompatible with browser-based JavaScript engines.
 
 #### `parseFile` function
@@ -269,7 +269,7 @@ import { createReadStream } from 'fs';
 
 ### Cross-platform functions
 These functions are designed to be cross-platform,
-meaning it can be used in both Node.js and web browsers.
+meaning they can be used in both Node.js and web browsers.
 
 #### `parseWebStream` function
 
@@ -295,14 +295,14 @@ parseWebStream(webStream: ReadableStream<Uint8Array>, fileInfo?: IFileInfo | str
   An object containing file-related information or a string representing the MIME-type of the audio stream.
   The fileInfo parameter can help the parser to correctly identify the audio format and may include:
 
-    - `mimeType`: A string representing the [MIME-type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) (e.g., `audio/mpeg`).
+  - `mimeType`: A string representing the [MIME-type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) (e.g., `audio/mpeg`).
 
-      If provided, it is assumed the streamed file content is to be the MIME-type.
-      If not provided, the parser will attempt to determine the format based on the content of the stream.
+    If provided, it is assumed the streamed file content is to be the MIME-type.
+    If not provided, the parser will attempt to determine the format based on the content of the stream.
 
-    - `size`: The total size of the audio stream in bytes (useful for streams with a known length).
+  - `size`: The total size of the audio stream in bytes (useful for streams with a known length).
 
-    - `path`: A string representing the file path or filename, which can also assist in determining the format.
+  - `path`: A string representing the file path or filename, which can also assist in determining the format.
 
 - `options`: `IOptions` (optional)
 
@@ -351,19 +351,19 @@ The `response.body` provides a [`ReadableStream`](https://developer.mozilla.org/
 #### `parseBlob` function
 
 Parses metadata from an audio file represented as a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob). 
-This function is suitable for use in environments that support the ReadableStreamBYOBReader, which is **available in Node.js 20** and above.
+This function reads slices of the Blob and supports both browser File objects and Node.js Blob objects.
 
 ##### Syntax
 ```ts
-parseBlob(blob: Blob, options?: IOptions = {}): Promise<IAudioMetadata>
+parseBlob(blob: Blob, options?: IOptions): Promise<IAudioMetadata>
 ```
 
 ##### Parameters
  
 - `blob`: [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
   
-   The Blob object containing the audio data to be parsed.
-   This can be a file or any binary data. If the Blob is an instance of File, its name will be used as the file path in the metadata.
+  The Blob object containing the audio data to be parsed.
+  This can be a File selected by the user or a Blob containing audio data. The Blob size and MIME type are passed to the parser.
 
 - `options`: [IOptions](#ioptions-interface) (optional)
   
@@ -400,7 +400,7 @@ This function is particularly useful when you already have audio data in memory.
 
 ##### Syntax
 ```ts
-parseBuffer(buffer: Uint8Array, fileInfo?: IFileInfo | string, opts?: IOptions = {}): Promise<IAudioMetadata>
+parseBuffer(uint8Array: Uint8Array, fileInfo?: IFileInfo | string, options?: IOptions): Promise<IAudioMetadata>
 ```
 
 ##### Parameters
@@ -518,12 +518,13 @@ readMetadata();
 
 ### Handling Parse Errors
 
-`music-metadata` provides a robust and extensible error handling system with custom error classes that inherit from the standard JavaScript `Error`.
-All possible parsing errors are part of a union type `UnionOfParseErrors`, ensuring that every error scenario is accounted for in your code.
+`music-metadata` exports custom error classes that extend JavaScript `Error`.
+Parsing can also reject with other errors, such as filesystem, stream, or tokenizer errors.
+Handle caught values as `unknown` in TypeScript and narrow them before accessing error properties.
 
 #### Union of Parse Errors 
 
-All parsing errors extend from the base class `ParseError` and are included in the `UnionOfParseErrors` type:
+The `UnionOfParseErrors` type groups the following library error classes; it does not describe every possible rejection:
 ```ts
 export type UnionOfParseErrors =
   | CouldNotDetermineFileTypeError
@@ -545,10 +546,10 @@ export type UnionOfParseErrors =
 
 #### `orderTags` function
 
-Utility to Converts the native tags to a dictionary index on the tag identifier
+Converts an array of native tags to a dictionary keyed by tag identifier. Each value is an array of tag values.
 
 ```ts
-orderTags(nativeTags: ITag[]): [tagId: string]: any[]
+orderTags(nativeTags: ITag[]): INativeTagDict
 ```
 
 ```js
@@ -571,7 +572,7 @@ import { inspect } from 'util';
    Can be used to convert the normalized rating value to the 0..5 stars, where 0 an undefined rating, 1 the star the lowest rating and 5 the highest rating.
 
    ```ts
-   ratingToStars(rating: number): number
+   ratingToStars(rating: number | undefined): number
    ```
 #### `selectCover` function
 
@@ -613,7 +614,7 @@ Returns a list of supported MIME-types. This may include some MIME-types which a
   - Metadata not listed in the SeekHead may be skipped.
   - If the SeekHead is missing, this option has no effect.
 
-- `observer`: `(update: MetadataEvent) => void;`:
+- `observer`: `(update: IMetadataEvent) => void`:
 
   Callback function triggered when common tags or format properties are updated during parsing.
   Allows real-time monitoring of metadata as it becomes available.
@@ -628,7 +629,7 @@ Returns a list of supported MIME-types. This may include some MIME-types which a
   This is particularly beneficial for streaming input, as it avoids the need to read the entire stream.
 
 > [!NOTE]
-> - The `duration` option is typically included in most cases, but setting it to true ensures that the entire file is parsed if necessary to get an accurate duration.
+> - `format.duration` may be available without enabling `duration`. Set `duration: true` to allow additional scanning when needed; duration can still be unavailable.
 > - Using `mkvUseIndex` can improve performance in Matroska files, but be aware of potential side effects, such as missing metadata due to skipped elements.
 
 
@@ -637,8 +638,9 @@ Returns a list of supported MIME-types. This may include some MIME-types which a
 If the returned promise resolves, the metadata (TypeScript `IAudioMetadata` interface) contains:
 - [`metadata.format`](#metadataformat) Audio format information
 - [`metadata.common`](#metadatacommon) Is a generic (abstract) way of reading metadata information.
-- [`metadata.trackInfo`](#metadatatrackInfo) Is a generic (abstract) way of reading metadata information.
-- `metadata.native` List of native (original) tags found in the parsed audio file.
+- [`metadata.format.trackInfo`](#metadataformattrackinfo) Describes individual audio and video tracks when available.
+- `metadata.native` Maps each tag format to an array of native (original) tags found in the parsed audio file.
+- `metadata.quality.warnings` Contains non-fatal parsing warnings, each with a `message` string.
 
 #### `metadata.format`
 
@@ -660,15 +662,16 @@ Audio format information. Defined in the TypeScript `IFormat` interface:
 - `format.trackGain?: number` Track gain in dB
 - `format.albumGain?: number` Album gain in dB
 
-#### `metadata.trackInfo`
+#### `metadata.format.trackInfo`
 
-To support advanced containers like [Matroska](https://wikipedia.org/wiki/Matroska) or [MPEG-4](https://en.wikipedia.org/wiki/MPEG-4), which may contain multiple audio and video tracks, the **experimental**- `metadata.trackInfo` has been added,
+Containers such as Matroska and MPEG-4 can contain multiple audio and video tracks.
+The experimental `metadata.format.trackInfo` property describes these individual tracks.
 
-`metadata.trackInfo` is either `undefined` or has an **array** of [trackInfo](#trackinfo)
+`metadata.format.trackInfo` is an array of [trackInfo](#trackinfo) objects, empty when no track information is available.
 
 ##### trackInfo
 
-Audio format information. Defined in the TypeScript `IFormat` interface:
+Individual track information. Defined in the TypeScript `ITrackInfo` interface:
 - `trackInfo.type?: TrackType` Track type
 - `trackInfo.codecName?: string` Codec name
 - `trackInfo.codecSettings?: string` Codec settings
@@ -685,7 +688,7 @@ Audio format information. Defined in the TypeScript `IFormat` interface:
 - `audioTrack.samplingFrequency?: number`
 - `audioTrack.outputSamplingFrequency?: number`
 - `audioTrack.channels?: number`
-- `audioTrack.channelPositions?: Buffer`
+- `audioTrack.channelPositions?: Uint8Array`
 - `audioTrack.bitDepth?: number`
 
 ##### `trackInfo.videoTrack`
@@ -698,7 +701,7 @@ Audio format information. Defined in the TypeScript `IFormat` interface:
 - `videoTrack.displayHeight?: number`
 - `videoTrack.displayUnit?: number`
 - `videoTrack.aspectRatioType?: number`
-- `videoTrack.colourSpace?: Buffer`
+- `videoTrack.colourSpace?: Uint8Array`
 - `videoTrack.gammaValue?: number`
 
 #### `metadata.common`
@@ -737,7 +740,7 @@ export interface IPicture {
   /**
    * Image data
    */
-  data: Buffer;
+  data: Uint8Array;
   /**
    * Optional description
    */

package/lib/ParserFactory.d.ts

@@ -1,7 +1,7 @@
 import { type MediaType } from 'media-typer';
+import type { ITokenizer } from 'strtok3';
 import { type INativeMetadataCollector } from './common/MetadataCollector.js';
 import { type IAudioMetadata, type IOptions, type ParserType } from './type.js';
-import type { ITokenizer } from 'strtok3';
 export interface IParserLoader {
     /**
      * Returns a list of supported file extensions

package/lib/ParserFactory.js

@@ -1,24 +1,24 @@
-import { fileTypeFromBuffer } from 'file-type';
 import ContentType from 'content-type';
-import { parse as mimeTypeParse } from 'media-typer';
 import initDebug from 'debug';
-import { MetadataCollector } from './common/MetadataCollector.js';
-import { TrackType } from './type.js';
-import { mpegParserLoader } from './mpeg/MpegLoader.js';
-import { CouldNotDetermineFileTypeError, UnsupportedFileTypeError } from './ParseError.js';
+import { fileTypeFromBuffer } from 'file-type';
+import { parse as mimeTypeParse } from 'media-typer';
+import { aiffParserLoader } from './aiff/AiffLoader.js';
 import { apeParserLoader } from './apev2/Apev2Loader.js';
 import { asfParserLoader } from './asf/AsfLoader.js';
+import { MetadataCollector } from './common/MetadataCollector.js';
+import { scanAppendingHeaders } from './core.js';
 import { dsdiffParserLoader } from './dsdiff/DsdiffLoader.js';
-import { aiffParserLoader } from './aiff/AiffLoader.js';
 import { dsfParserLoader } from './dsf/DsfLoader.js';
 import { flacParserLoader } from './flac/FlacLoader.js';
 import { matroskaParserLoader } from './matroska/MatroskaLoader.js';
 import { mp4ParserLoader } from './mp4/Mp4Loader.js';
+import { mpegParserLoader } from './mpeg/MpegLoader.js';
 import { musepackParserLoader } from './musepack/MusepackLoader.js';
 import { oggParserLoader } from './ogg/OggLoader.js';
-import { wavpackParserLoader } from './wavpack/WavPackLoader.js';
+import { CouldNotDetermineFileTypeError, UnsupportedFileTypeError } from './ParseError.js';
+import { TrackType } from './type.js';
 import { riffParserLoader } from './wav/WaveLoader.js';
-import { scanAppendingHeaders } from './core.js';
+import { wavpackParserLoader } from './wavpack/WavPackLoader.js';
 const debug = initDebug('music-metadata:parser:factory');
 export function parseHttpContentType(contentType) {
     const type = ContentType.parse(contentType);
@@ -47,7 +47,9 @@ export class ParserFactory {
             musepackParserLoader,
             dsfParserLoader,
             dsdiffParserLoader
-        ].forEach(parser => { this.registerParser(parser); });
+        ].forEach(parser => {
+            this.registerParser(parser);
+        });
     }
     registerParser(parser) {
         this.parsers.push(parser);
@@ -73,7 +75,7 @@ export class ParserFactory {
                 debug('Guess parser on content...');
                 await tokenizer.peekBuffer(buf, { mayBeLess: true });
                 const guessedType = await fileTypeFromBuffer(buf, { mpegOffsetTolerance: 10 });
-                if (!guessedType || !guessedType.mime) {
+                if (!guessedType?.mime) {
                     throw new CouldNotDetermineFileTypeError('Failed to determine audio format');
                 }
                 debug(`Guessed file type is mime=${guessedType.mime}, extension=${guessedType.ext}`);
@@ -105,15 +107,17 @@ export class ParserFactory {
      * @return Parser submodule name
      */
     findLoaderForExtension(filePath) {
-        if (!filePath)
+        if (!filePath) {
             return;
+        }
         const extension = getExtension(filePath).toLocaleLowerCase() || filePath;
         return this.parsers.find(parser => parser.extensions.indexOf(extension) !== -1);
     }
     findLoaderForContentType(httpContentType) {
         let mime;
-        if (!httpContentType)
+        if (!httpContentType) {
             return;
+        }
         try {
             mime = parseHttpContentType(httpContentType);
         }

package/lib/aiff/AiffParser.js

@@ -1,12 +1,12 @@
-import * as Token from 'token-types';
 import initDebug from 'debug';
 import * as strtok3 from 'strtok3';
-import { ID3v2Parser } from '../id3v2/ID3v2Parser.js';
-import { FourCcToken } from '../common/FourCC.js';
+import * as Token from 'token-types';
 import { BasicParser } from '../common/BasicParser.js';
+import { FourCcToken } from '../common/FourCC.js';
+import { ID3v2Parser } from '../id3v2/ID3v2Parser.js';
+import * as iff from '../iff/index.js';
 import * as AiffToken from './AiffToken.js';
 import { AiffContentError, compressionTypes } from './AiffToken.js';
-import * as iff from '../iff/index.js';
 const debug = initDebug('music-metadata:parser:aiff');
 /**
  * AIFF - Audio Interchange File Format
@@ -22,8 +22,9 @@ export class AIFFParser extends BasicParser {
     }
     async parse() {
         const header = await this.tokenizer.readToken(iff.Header);
-        if (header.chunkID !== 'FORM')
-            throw new AiffContentError('Invalid Chunk-ID, expected \'FORM\''); // Not AIFF format
+        if (header.chunkID !== 'FORM') {
+            throw new AiffContentError("Invalid Chunk-ID, expected 'FORM'"); // Not AIFF format
+        }
         const type = await this.tokenizer.readToken(FourCcToken);
         switch (type) {
             case 'AIFF':
@@ -40,7 +41,8 @@ export class AIFFParser extends BasicParser {
         this.metadata.setFormat('lossless', !this.isCompressed);
         this.metadata.setAudioOnly();
         try {
-            while (!this.tokenizer.fileInfo.size || this.tokenizer.fileInfo.size - this.tokenizer.position >= iff.Header.len) {
+            while (!this.tokenizer.fileInfo.size ||
+                this.tokenizer.fileInfo.size - this.tokenizer.position >= iff.Header.len) {
                 debug(`Reading AIFF chunk at offset=${this.tokenizer.position}`);
                 const chunkHeader = await this.tokenizer.readToken(iff.Header);
                 const nextChunk = 2 * Math.round(chunkHeader.chunkSize / 2);
@@ -50,7 +52,7 @@ export class AIFFParser extends BasicParser {
         }
         catch (err) {
             if (err instanceof strtok3.EndOfStreamError) {
-                debug("End-of-stream");
+                debug('End-of-stream');
             }
             else {
                 throw err;
@@ -59,7 +61,8 @@ export class AIFFParser extends BasicParser {
     }
     async readData(header) {
         switch (header.chunkID) {
-            case 'COMM': { // The Common Chunk
+            case 'COMM': {
+                // The Common Chunk
                 if (this.isCompressed === null) {
                     throw new AiffContentError('Failed to parse AIFF.COMM chunk when compression type is unknown');
                 }
@@ -74,7 +77,8 @@ export class AIFFParser extends BasicParser {
                 }
                 return header.chunkSize;
             }
-            case 'ID3 ': { // ID3-meta-data
+            case 'ID3 ': {
+                // ID3-meta-data
                 const id3_data = await this.tokenizer.readToken(new Token.Uint8ArrayType(header.chunkSize));
                 const rst = strtok3.fromBuffer(id3_data);
                 await new ID3v2Parser().parse(this.metadata, rst, this.options);
@@ -82,7 +86,7 @@ export class AIFFParser extends BasicParser {
             }
             case 'SSND': // Sound Data Chunk
                 if (this.metadata.format.duration) {
-                    this.metadata.setFormat('bitrate', 8 * header.chunkSize / this.metadata.format.duration);
+                    this.metadata.setFormat('bitrate', (8 * header.chunkSize) / this.metadata.format.duration);
                 }
                 return 0;
             case 'NAME': // Sample name chunk
@@ -97,7 +101,10 @@ export class AIFFParser extends BasicParser {
     }
     async readTextChunk(header) {
         const value = await this.tokenizer.readToken(new Token.StringType(header.chunkSize, 'ascii'));
-        const values = value.split('\0').map(v => v.trim()).filter(v => v?.length);
+        const values = value
+            .split('\0')
+            .map(v => v.trim())
+            .filter(v => v?.length);
         await Promise.all(values.map(v => this.metadata.addTag('AIFF', header.chunkID, v)));
         return header.chunkSize;
     }

package/lib/aiff/AiffToken.d.ts

@@ -1,5 +1,5 @@
-import type * as iff from '../iff/index.js';
 import type { IGetToken } from 'strtok3';
+import type * as iff from '../iff/index.js';
 export declare const compressionTypes: {
     NONE: string;
     sowt: string;

package/lib/aiff/AiffToken.js

@@ -18,8 +18,9 @@ export class Common {
     constructor(header, isAifc) {
         this.isAifc = isAifc;
         const minimumChunkSize = isAifc ? 22 : 18;
-        if (header.chunkSize < minimumChunkSize)
+        if (header.chunkSize < minimumChunkSize) {
             throw new AiffContentError(`COMMON CHUNK size should always be at least ${minimumChunkSize}`);
+        }
         this.len = header.chunkSize;
     }
     get(buf, off) {

package/lib/apev2/APEv2Parser.d.ts

@@ -1,9 +1,9 @@
+import type { IRandomAccessTokenizer } from 'strtok3';
 import * as strtok3 from 'strtok3';
-import type { IOptions, IApeHeader } from '../type.js';
-import type { INativeMetadataCollector } from '../common/MetadataCollector.js';
 import { BasicParser } from '../common/BasicParser.js';
+import type { INativeMetadataCollector } from '../common/MetadataCollector.js';
+import type { IApeHeader, IOptions } from '../type.js';
 import { type IFooter, type IHeader } from './APEv2Token.js';
-import type { IRandomAccessTokenizer } from 'strtok3';
 declare const ApeContentError_base: {
     new (message: string): {
         readonly fileType: string;
@@ -40,6 +40,7 @@ export declare class APEv2Parser extends BasicParser {
     tryParseApeHeader(): Promise<void>;
     parse(): Promise<void>;
     parseTags(footer: IFooter): Promise<void>;
+    private readTagValue;
     private parseDescriptorExpansion;
     private parseHeader;
 }

package/lib/apev2/APEv2Parser.js

@@ -1,11 +1,11 @@
+import { textDecode } from '@borewit/text-codec';
 import initDebug from 'debug';
 import * as strtok3 from 'strtok3';
 import { StringType } from 'token-types';
-import * as util from '../common/Util.js';
 import { BasicParser } from '../common/BasicParser.js';
-import { DataType, DescriptorParser, Header, TagFooter, TagItemHeader } from './APEv2Token.js';
+import * as util from '../common/Util.js';
 import { makeUnexpectedFileContentError } from '../ParseError.js';
-import { textDecode } from '@borewit/text-codec';
+import { DataType, DescriptorParser, Header, TagFooter, TagItemHeader } from './APEv2Token.js';
 const debug = initDebug('music-metadata:parser:APEv2');
 const tagFormat = 'APEv2';
 const preamble = 'APETAGEX';
@@ -61,8 +61,9 @@ export class APEv2Parser extends BasicParser {
     }
     static parseTagFooter(metadata, buffer, options) {
         const footer = TagFooter.get(buffer, buffer.length - TagFooter.len);
-        if (footer.ID !== preamble)
+        if (footer.ID !== preamble) {
             throw new ApeContentError('Unexpected APEv2 Footer ID preamble value');
+        }
         strtok3.fromBuffer(buffer);
         const apeParser = new APEv2Parser(metadata, strtok3.fromBuffer(buffer), options);
         return apeParser.parseTags(footer);
@@ -72,7 +73,7 @@ export class APEv2Parser extends BasicParser {
      */
     async tryParseApeHeader() {
         if (this.tokenizer.fileInfo.size && this.tokenizer.fileInfo.size - this.tokenizer.position < TagFooter.len) {
-            debug("No APEv2 header found, end-of-file reached");
+            debug('No APEv2 header found, end-of-file reached');
             return;
         }
         const footer = await this.tokenizer.peekToken(TagFooter);
@@ -91,8 +92,9 @@ export class APEv2Parser extends BasicParser {
     }
     async parse() {
         const descriptor = await this.tokenizer.readToken(DescriptorParser);
-        if (descriptor.ID !== 'MAC ')
+        if (descriptor.ID !== 'MAC ') {
             throw new ApeContentError('Unexpected descriptor ID');
+        }
         this.ape.descriptor = descriptor;
         const lenExp = descriptor.descriptorBytes - DescriptorParser.len;
         const header = await (lenExp > 0 ? this.parseDescriptorExpansion(lenExp) : this.parseHeader());
@@ -111,15 +113,31 @@ export class APEv2Parser extends BasicParser {
             }
             // Only APEv2 tag has tag item headers
             const tagItemHeader = await this.tokenizer.readToken(TagItemHeader);
-            bytesRemaining -= TagItemHeader.len + tagItemHeader.size;
-            await this.tokenizer.peekBuffer(keyBuffer, { length: Math.min(keyBuffer.length, bytesRemaining) });
-            let zero = util.findZero(keyBuffer);
+            bytesRemaining -= TagItemHeader.len;
+            // Reserve the value bytes before looking for the key terminator.
+            if (tagItemHeader.size >= bytesRemaining) {
+                throw new ApeContentError(`Invalid tag item size: ${tagItemHeader.size}`);
+            }
+            const keyBytes = await this.tokenizer.peekBuffer(keyBuffer, {
+                length: Math.min(keyBuffer.length, bytesRemaining - tagItemHeader.size),
+                mayBeLess: true
+            });
+            let zero = keyBuffer.subarray(0, keyBytes).indexOf(0);
+            if (zero === -1) {
+                throw new ApeContentError('Unterminated tag item key');
+            }
             const key = await this.tokenizer.readToken(new StringType(zero, 'ascii'));
             await this.tokenizer.ignore(1);
             bytesRemaining -= key.length + 1;
+            if (this.tokenizer.fileInfo.size !== undefined &&
+                tagItemHeader.size > this.tokenizer.fileInfo.size - this.tokenizer.position) {
+                throw new ApeContentError(`Invalid tag item size: ${tagItemHeader.size}`);
+            }
+            bytesRemaining -= tagItemHeader.size;
             switch (tagItemHeader.flags.dataType) {
-                case DataType.text_utf8: { // utf-8 text-string
-                    const value = await this.tokenizer.readToken(new StringType(tagItemHeader.size, 'utf8'));
+                case DataType.text_utf8: {
+                    // utf-8 text-string
+                    const value = textDecode(await this.readTagValue(tagItemHeader.size), 'utf-8');
                     const values = value.split(/\x00/g);
                     await Promise.all(values.map(val => this.metadata.addTag(tagFormat, key, val)));
                     break;
@@ -129,8 +147,7 @@ export class APEv2Parser extends BasicParser {
                         await this.tokenizer.ignore(tagItemHeader.size);
                     }
                     else {
-                        const picData = new Uint8Array(tagItemHeader.size);
-                        await this.tokenizer.readBuffer(picData);
+                        const picData = await this.readTagValue(tagItemHeader.size);
                         zero = util.findZero(picData);
                         const description = textDecode(picData.subarray(0, zero), 'utf-8');
                         const data = picData.subarray(zero + 1);
@@ -152,6 +169,30 @@ export class APEv2Parser extends BasicParser {
             }
         }
     }
+    async readTagValue(size) {
+        const chunkSize = 64 * 1024;
+        if ((!this.tokenizer.supportsRandomAccess() || this.tokenizer.fileInfo.size === undefined) && size > chunkSize) {
+            // Stream sizes may be unknown or untrustworthy. Only allocate the full
+            // value after all of its bytes have actually been read.
+            const chunks = [];
+            for (let remaining = size; remaining > 0;) {
+                const chunk = new Uint8Array(Math.min(remaining, chunkSize));
+                await this.tokenizer.readBuffer(chunk);
+                chunks.push(chunk);
+                remaining -= chunk.length;
+            }
+            const value = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                value.set(chunk, offset);
+                offset += chunk.length;
+            }
+            return value;
+        }
+        const value = new Uint8Array(size);
+        await this.tokenizer.readBuffer(value);
+        return value;
+    }
     async parseDescriptorExpansion(lenExp) {
         await this.tokenizer.ignore(lenExp);
         return this.parseHeader();
@@ -160,7 +201,7 @@ export class APEv2Parser extends BasicParser {
         const header = await this.tokenizer.readToken(Header);
         // ToDo before
         this.metadata.setFormat('lossless', true);
-        this.metadata.setFormat('container', 'Monkey\'s Audio');
+        this.metadata.setFormat('container', "Monkey's Audio");
         this.metadata.setFormat('bitsPerSample', header.bitsPerSample);
         this.metadata.setFormat('sampleRate', header.sampleRate);
         this.metadata.setFormat('numberOfChannels', header.channel);
@@ -169,8 +210,10 @@ export class APEv2Parser extends BasicParser {
             throw new ApeContentError('Missing APE descriptor');
         }
         return {
-            forwardBytes: this.ape.descriptor.seekTableBytes + this.ape.descriptor.headerDataBytes +
-                this.ape.descriptor.apeFrameDataBytes + this.ape.descriptor.terminatingDataBytes
+            forwardBytes: this.ape.descriptor.seekTableBytes +
+                this.ape.descriptor.headerDataBytes +
+                this.ape.descriptor.apeFrameDataBytes +
+                this.ape.descriptor.terminatingDataBytes
         };
     }
 }

package/lib/apev2/APEv2TagMapper.js

@@ -9,6 +9,7 @@ const apev2TagMap = {
     'Album Artist': 'albumartist',
     Album: 'album',
     Year: 'date',
+    Date: 'date',
     Originalyear: 'originalyear',
     Originaldate: 'originaldate',
     Releasedate: 'releasedate',

package/lib/apev2/APEv2Token.d.ts

@@ -58,7 +58,7 @@ export declare const DataType: {
     external_info: number;
     reserved: number;
 };
-export type DataType = typeof DataType[keyof typeof DataType];
+export type DataType = (typeof DataType)[keyof typeof DataType];
 /**
  * APE_DESCRIPTOR: defines the sizes (and offsets) of all the pieces, as well as the MD5 checksum
  */

package/lib/apev2/APEv2Token.js

@@ -112,5 +112,5 @@ export function parseTagFlags(flags) {
  * @return {boolean} true if bit is 1; otherwise false
  */
 export function isBitSet(num, bit) {
-    return (num & 1 << bit) !== 0;
+    return (num & (1 << bit)) !== 0;
 }