music-metadata 10.1.0 → 10.2.0

package/README.md

@@ -11,15 +11,31 @@
 
 # music-metadata
 
-Stream and file based music metadata parser for [node.js](https://nodejs.org/) and browser projects.
-Supports any common audio and tagging format.
+Key features:
+* **Comprehensive Format Support**: Supports popular audio formats like MP3, MP4, FLAC, Ogg, WAV, AIFF, and more.
+* **Extensive Metadata Extraction**: Extracts detailed metadata, including ID3v1, ID3v2, APE, Vorbis, and iTunes/MP4 tags.
+* **Streaming Support**: Efficiently handles large audio files by reading metadata from streams, making it suitable for server-side and browser-based applications.
+* **Promise-Based API**: Provides a modern, promise-based API for easy integration into asynchronous workflows.
+* **Cross-Platform**: Works in both [Node.js](https://nodejs.org/) and browser environments with the help of bundlers like [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/introduction/).
+
+The [`music-metadata`](https://github.com/Borewit/music-metadata) module is ideal for developers working on media applications, music players, or any project that requires access to detailed audio file metadata.
 
 ## Compatibility
 
 Module: version 8 migrated from [CommonJS](https://en.wikipedia.org/wiki/CommonJS) to [pure ECMAScript Module (ESM)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
-JavaScript is compliant with [ECMAScript 2019 (ES10)](https://en.wikipedia.org/wiki/ECMAScript#10th_Edition_%E2%80%93_ECMAScript_2019).
-Requires Node.js ≥ 16 engine.
-Primarily designed for [Node.js](https://nodejs.org/), but has also been designed for browser compatibility. 
+The distributed JavaScript codebase is compliant with the [ECMAScript 2020 (11th Edition)](https://en.wikipedia.org/wiki/ECMAScript_version_history#11th_Edition_%E2%80%93_ECMAScript_2020) standard.
+
+This module requires a [Node.js ≥ 16](https://nodejs.org/en/about/previous-releases) engine.
+It can also be used in a browser environment when bundled with a module bundler.
+
+## Sponsor
+If you appreciate my work and want to support the development of open-source projects like [music-metadata](https://github.com/Borewit/music-metadata), [file-type](https://github.com/sindresorhus/file-type), and [listFix()](https://github.com/Borewit/listFix), consider becoming a sponsor or making a small contribution.
+Your support helps sustain ongoing development and improvements.
+[Become a sponsor to Borewit](https://github.com/sponsors/Borewit)
+
+or
+
+<a href="https://www.buymeacoffee.com/borewit" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy me A coffee" height="41" width="174"></a>
 
 ## Features
 
@@ -81,11 +97,6 @@ Support for encoding / format details:
 - [<img src="https://cdn.sanity.io/images/3do82whm/next/ba8c847f13a5fa39d88f8bc9b7846b7886531b18-2500x2500.svg" width="40"> Webamp](https://webamp.org/)
 
 
-### Sponsor
-[Become a sponsor to Borewit](https://github.com/sponsors/Borewit)
-
-<a href="https://www.buymeacoffee.com/borewit" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy me A coffee" height="41" width="174"></a>
-
 ## Dependencies
 
 Dependency diagram:
@@ -192,7 +203,7 @@ An extension (e.g.: `.mp3`), filename or path will also work.
 If the MIME-type or filename (via `fileInfo.path`) is not provided, or not understood, music-metadata will try to derive the type from the content.
 
 ```ts
-parseStream(stream: Stream.Readable, fileInfo?: IFileInfo | string, opts?: IOptions = {}): Promise<IAudioMetadata>`
+parseStream(stream: Stream.Readable, fileInfo?: IFileInfo | string, opts?: IOptions = {}): Promise<IAudioMetadata>
 ```
 
 Example:
@@ -327,7 +338,11 @@ import { parseFile, selectCover } from 'music-metadata';
 - `observer: (update: MetadataEvent) => void;`: Will be called after each change to `common` (generic) tag, or `format` properties.
 - `skipCovers`: default: `false`, if set to `true`, it will not return embedded cover-art (images).
 - `skipPostHeaders? boolean` default: `false`, if set to `true`, it will not search all the entire track for additional headers. Only recommenced to use in combination with streams.
-- `includeChapters` default: `false`, if set to `true`, it will parse chapters (currently only MP4 files). _experimental functionality_
+- `mkvUseIndex` default: `false`, if set to `true`, in Matroska based files, use the _SeekHead_ element index to skip _segment/cluster_ elements.. 
+  _experimental functionality_
+  Can have a significant performance impact if enabled.
+  Possible side effect can be that certain metadata maybe skipped, depending on the index.
+  If there is no _SeekHead_ element present in the Matroska file, this flag has no effect.
 
 Although in most cases duration is included, in some cases it requires `music-metadata` parsing the entire file.
 To enforce parsing the entire file if needed you should set `duration` to `true`.
@@ -362,7 +377,7 @@ Audio format information. Defined in the TypeScript `IFormat` interface:
 
 #### `metadata.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,
+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,
 
 `metadata.trackInfo` is either `undefined` or has an **array** of [trackInfo](#trackinfo)
 
@@ -483,29 +498,29 @@ img.src = `data:${picture.format};base64,${uint8ArrayToBase64(picture.data)}`;
 
         ```
 
-    2.  Use async/await
+    1. Use async/await
 
-        Use [async/await](https://javascript.info/async-await)
+       Use [async/await](https://javascript.info/async-await)
 
-        ```js
-        import { parseFile } from 'music-metadata';
+       ```js
+       import { parseFile } from 'music-metadata';
 
-        // it is required to declare the function 'async' to allow the use of await
-        async function parseFiles(audioFiles) {
+       // it is required to declare the function 'async' to allow the use of await
+       async function parseFiles(audioFiles) {
 
-            for (const audioFile of audioFiles) {
+           for (const audioFile of audioFiles) {
 
-                // await will ensure the metadata parsing is completed before we move on to the next file
-                const metadata = await parseFile(audioFile);
-                // Do great things with the metadata
-            }
-        }
-        ```
+               // await will ensure the metadata parsing is completed before we move on to the next file
+               const metadata = await parseFile(audioFile);
+               // Do great things with the metadata
+           }
+       }
+       ```
 
-    3.  Use a specialized module to traverse files
+    1. Use a specialized module to traverse files
 
-        There are specialized modules to traversing (walking) files and directory,
-        like [walk](https://www.npmjs.com/package/walk).
+       There are specialized modules to traversing (walking) files and directory,
+       like [walk](https://www.npmjs.com/package/walk).
 
 ## Licence
 

package/lib/ParserFactory.js

@@ -66,7 +66,7 @@ export async function parse(tokenizer, parserId, opts) {
     // Parser found, execute parser
     const parser = await loadParser(parserId);
     const metadata = new MetadataCollector(opts);
-    await parser.init(metadata, tokenizer, opts !== null && opts !== void 0 ? opts : {}).parse();
+    await parser.init(metadata, tokenizer, opts ?? {}).parse();
     return metadata.toCommonMetadata();
 }
 /**

package/lib/aiff/AiffParser.js

@@ -57,7 +57,6 @@ export class AIFFParser extends BasicParser {
         }
     }
     async readData(header) {
-        var _a;
         switch (header.chunkID) {
             case 'COMM': { // The Common Chunk
                 if (this.isCompressed === null) {
@@ -70,7 +69,7 @@ export class AIFFParser extends BasicParser {
                 this.metadata.setFormat('numberOfSamples', common.numSampleFrames);
                 this.metadata.setFormat('duration', common.numSampleFrames / common.sampleRate);
                 if (common.compressionName || common.compressionType) {
-                    this.metadata.setFormat('codec', (_a = common.compressionName) !== null && _a !== void 0 ? _a : compressionTypes[common.compressionType]);
+                    this.metadata.setFormat('codec', common.compressionName ?? compressionTypes[common.compressionType]);
                 }
                 return header.chunkSize;
             }
@@ -97,7 +96,7 @@ 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 === null || v === void 0 ? void 0 : 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/common/MetadataCollector.js

@@ -54,10 +54,9 @@ export class MetadataCollector {
         this.format.trackInfo.push(streamInfo);
     }
     setFormat(key, value) {
-        var _a;
         debug(`format: ${key} = ${value}`);
         this.format[key] = value; // as any to override readonly
-        if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.observer) {
+        if (this.opts?.observer) {
             this.opts.observer({ metadata: this, tag: { type: 'format', id: key, value } });
         }
     }
@@ -239,7 +238,6 @@ export class MetadataCollector {
      * Set generic tag
      */
     setGenericTag(tagType, tag) {
-        var _a;
         debug(`common.${tag.id} = ${tag.value}`);
         const prio0 = this.commonOrigin[tag.id] || 1000;
         const prio1 = this.originPriority[tagType];
@@ -270,7 +268,7 @@ export class MetadataCollector {
                 return debug(`Ignore native tag (list): ${tagType}.${tag.id} = ${tag.value}`);
             }
         }
-        if ((_a = this.opts) === null || _a === void 0 ? void 0 : _a.observer) {
+        if (this.opts?.observer) {
             this.opts.observer({ metadata: this, tag: { type: 'common', id: tag.id, value: tag.value } });
         }
         // ToDo: trigger metadata event

package/lib/ebml/EbmlIterator.d.ts

@@ -0,0 +1,52 @@
+import { type ITokenizer } from 'strtok3';
+import { type IElementType, type ITree, type ValueType } from './types.js';
+export interface ILinkedElementType extends IElementType {
+    id: number;
+    parent: ILinkedElementType | undefined;
+    readonly container?: {
+        [id: number]: ILinkedElementType;
+    };
+}
+export declare enum ParseAction {
+    ReadNext = 0,// Continue reading the next elements
+    IgnoreElement = 2,// Ignore (do not read) this element
+    SkipSiblings = 3,// Skip all remaining elements at the same level
+    TerminateParsing = 4,// Terminate the parsing process
+    SkipElement = 5
+}
+/**
+ * @return true, to quit the parser
+ */
+export type IElementListener = {
+    startNext: (dtdElement: ILinkedElementType) => ParseAction;
+    elementValue: (dtdElement: ILinkedElementType, value: ValueType, offset: number) => Promise<void>;
+};
+/**
+ * Extensible Binary Meta Language (EBML) iterator
+ * https://en.wikipedia.org/wiki/Extensible_Binary_Meta_Language
+ * http://matroska.sourceforge.net/technical/specs/rfc/index.html
+ *
+ * WEBM VP8 AUDIO FILE
+ */
+export declare class EbmlIterator {
+    private tokenizer;
+    private padding;
+    private parserMap;
+    private ebmlMaxIDLength;
+    private ebmlMaxSizeLength;
+    /**
+     * @param {ITokenizer} tokenizer Input
+     * @param tokenizer
+     */
+    constructor(tokenizer: ITokenizer);
+    iterate(dtdElement: IElementType, posDone: number, listener: IElementListener): Promise<ITree>;
+    private parseContainer;
+    private readVintData;
+    private readElement;
+    private readFloat;
+    private readFlag;
+    private readUint;
+    private readString;
+    private readBuffer;
+}
+export declare function getElementPath(element: ILinkedElementType): string;

package/lib/ebml/EbmlIterator.js

@@ -0,0 +1,220 @@
+import { Float32_BE, Float64_BE, StringType, UINT8 } from 'token-types';
+import initDebug from 'debug';
+import { EndOfStreamError } from 'strtok3';
+import { DataType } from './types.js';
+import * as Token from 'token-types';
+const debug = initDebug('music-metadata:parser:ebml');
+export var ParseAction;
+(function (ParseAction) {
+    ParseAction[ParseAction["ReadNext"] = 0] = "ReadNext";
+    ParseAction[ParseAction["IgnoreElement"] = 2] = "IgnoreElement";
+    ParseAction[ParseAction["SkipSiblings"] = 3] = "SkipSiblings";
+    ParseAction[ParseAction["TerminateParsing"] = 4] = "TerminateParsing";
+    ParseAction[ParseAction["SkipElement"] = 5] = "SkipElement"; // Consider the element has read, assume position is at the next element
+})(ParseAction || (ParseAction = {}));
+/**
+ * Extensible Binary Meta Language (EBML) iterator
+ * https://en.wikipedia.org/wiki/Extensible_Binary_Meta_Language
+ * http://matroska.sourceforge.net/technical/specs/rfc/index.html
+ *
+ * WEBM VP8 AUDIO FILE
+ */
+export class EbmlIterator {
+    /**
+     * @param {ITokenizer} tokenizer Input
+     * @param tokenizer
+     */
+    constructor(tokenizer) {
+        this.tokenizer = tokenizer;
+        this.padding = 0;
+        this.parserMap = new Map();
+        this.ebmlMaxIDLength = 4;
+        this.ebmlMaxSizeLength = 8;
+        this.parserMap.set(DataType.uint, e => this.readUint(e));
+        this.parserMap.set(DataType.string, e => this.readString(e));
+        this.parserMap.set(DataType.binary, e => this.readBuffer(e));
+        this.parserMap.set(DataType.uid, async (e) => this.readBuffer(e));
+        this.parserMap.set(DataType.bool, e => this.readFlag(e));
+        this.parserMap.set(DataType.float, e => this.readFloat(e));
+    }
+    async iterate(dtdElement, posDone, listener) {
+        return this.parseContainer(linkParents(dtdElement), posDone, listener);
+    }
+    async parseContainer(dtdElement, posDone, listener) {
+        const tree = {};
+        while (this.tokenizer.position < posDone) {
+            let element;
+            const elementPosition = this.tokenizer.position;
+            try {
+                element = await this.readElement();
+            }
+            catch (error) {
+                if (error instanceof EndOfStreamError) {
+                    break;
+                }
+                throw error;
+            }
+            const child = dtdElement.container[element.id];
+            if (child) {
+                const action = listener.startNext(child);
+                switch (action) {
+                    case ParseAction.ReadNext:
+                        {
+                            if (element.id === 0x1F43B675) {
+                                // Hack to ignore remaining segment, when cluster element received
+                                // await this.tokenizer.ignore(posDone - this.tokenizer.position);
+                                // break;
+                            }
+                            debug(`Read element: name=${getElementPath(child)}{id=0x${element.id.toString(16)}, container=${!!child.container}} at position=${elementPosition}`);
+                            if (child.container) {
+                                const res = await this.parseContainer(child, element.len >= 0 ? this.tokenizer.position + element.len : -1, listener);
+                                if (child.multiple) {
+                                    if (!tree[child.name]) {
+                                        tree[child.name] = [];
+                                    }
+                                    tree[child.name].push(res);
+                                }
+                                else {
+                                    tree[child.name] = res;
+                                }
+                                await listener.elementValue(child, res, elementPosition);
+                            }
+                            else {
+                                const parser = this.parserMap.get(child.value);
+                                if (typeof parser === 'function') {
+                                    const value = await parser(element);
+                                    tree[child.name] = value;
+                                    await listener.elementValue(child, value, elementPosition);
+                                }
+                            }
+                        }
+                        break;
+                    case ParseAction.SkipElement:
+                        debug(`Go to next element: name=${getElementPath(child)}, element.id=0x${element.id}, container=${!!child.container} at position=${elementPosition}`);
+                        break;
+                    case ParseAction.IgnoreElement:
+                        debug(`Ignore element: name=${getElementPath(child)}, element.id=0x${element.id}, container=${!!child.container} at position=${elementPosition}`);
+                        await this.tokenizer.ignore(element.len);
+                        break;
+                    case ParseAction.SkipSiblings:
+                        debug(`Ignore remaining container, at: name=${getElementPath(child)}, element.id=0x${element.id}, container=${!!child.container} at position=${elementPosition}`);
+                        await this.tokenizer.ignore(posDone - this.tokenizer.position);
+                        break;
+                    case ParseAction.TerminateParsing:
+                        debug(`Terminate parsing at element: name=${getElementPath(child)}, element.id=0x${element.id}, container=${!!child.container} at position=${elementPosition}`);
+                        return tree;
+                }
+            }
+            else {
+                switch (element.id) {
+                    case 0xec: // void
+                        this.padding += element.len;
+                        await this.tokenizer.ignore(element.len);
+                        break;
+                    default:
+                        debug(`parseEbml: parent=${getElementPath(dtdElement)}, unknown child: id=${element.id.toString(16)} at position=${elementPosition}`);
+                        this.padding += element.len;
+                        await this.tokenizer.ignore(element.len);
+                }
+            }
+        }
+        return tree;
+    }
+    async readVintData(maxLength) {
+        const msb = await this.tokenizer.peekNumber(UINT8);
+        let mask = 0x80;
+        let oc = 1;
+        // Calculate VINT_WIDTH
+        while ((msb & mask) === 0) {
+            if (oc > maxLength) {
+                throw new Error('VINT value exceeding maximum size');
+            }
+            ++oc;
+            mask >>= 1;
+        }
+        const id = new Uint8Array(oc);
+        await this.tokenizer.readBuffer(id);
+        return id;
+    }
+    async readElement() {
+        const id = await this.readVintData(this.ebmlMaxIDLength);
+        const lenField = await this.readVintData(this.ebmlMaxSizeLength);
+        lenField[0] ^= 0x80 >> (lenField.length - 1);
+        return {
+            id: readUIntBE(id, id.length),
+            len: readUIntBE(lenField, lenField.length)
+        };
+    }
+    async readFloat(e) {
+        switch (e.len) {
+            case 0:
+                return 0.0;
+            case 4:
+                return this.tokenizer.readNumber(Float32_BE);
+            case 8:
+                return this.tokenizer.readNumber(Float64_BE);
+            case 10:
+                return this.tokenizer.readNumber(Float64_BE);
+            default:
+                throw new Error(`Invalid IEEE-754 float length: ${e.len}`);
+        }
+    }
+    async readFlag(e) {
+        return (await this.readUint(e)) === 1;
+    }
+    async readUint(e) {
+        const buf = await this.readBuffer(e);
+        return readUIntBE(buf, e.len);
+    }
+    async readString(e) {
+        const rawString = await this.tokenizer.readToken(new StringType(e.len, 'utf-8'));
+        return rawString.replace(/\x00.*$/g, '');
+    }
+    async readBuffer(e) {
+        const buf = new Uint8Array(e.len);
+        await this.tokenizer.readBuffer(buf);
+        return buf;
+    }
+}
+function readUIntBE(buf, len) {
+    return Number(readUIntBeAsBigInt(buf, len));
+}
+/**
+ * Reeds an unsigned integer from a big endian buffer of length `len`
+ * @param buf Buffer to decode from
+ * @param len Number of bytes
+ * @private
+ */
+function readUIntBeAsBigInt(buf, len) {
+    const normalizedNumber = new Uint8Array(8);
+    const cleanNumber = buf.subarray(0, len);
+    try {
+        normalizedNumber.set(cleanNumber, 8 - len);
+        return Token.UINT64_BE.get(normalizedNumber, 0);
+    }
+    catch (error) {
+        return BigInt(-1);
+    }
+}
+function linkParents(element) {
+    if (element.container) {
+        Object.keys(element.container)
+            .map(id => {
+            const child = element.container[id];
+            child.id = Number.parseInt(id);
+            return child;
+        }).forEach(child => {
+            child.parent = element;
+            linkParents(child);
+        });
+    }
+    return element;
+}
+export function getElementPath(element) {
+    let path = '';
+    if (element.parent && element.parent.name !== 'dtd') {
+        path += `${getElementPath(element.parent)}/`;
+    }
+    return path + element.name;
+}
+//# sourceMappingURL=EbmlIterator.js.map

package/lib/ebml/types.d.ts

@@ -0,0 +1,36 @@
+export interface ITree {
+    [name: string]: string | number | boolean | Uint8Array | ITree | ITree[];
+}
+export declare enum DataType {
+    'string' = 0,
+    uint = 1,
+    uid = 2,
+    bool = 3,
+    binary = 4,
+    float = 5
+}
+export type ValueType = string | number | Uint8Array | boolean | ITree | ITree[];
+export interface IHeader {
+    id: number;
+    len: number;
+}
+export interface IEbmlElements {
+    version?: number;
+    readVersion?: number;
+    maxIDWidth?: number;
+    maxSizeWidth?: number;
+    docType?: string;
+    docTypeVersion?: number;
+    docTypeReadVersion?: number;
+}
+export interface IElementType {
+    readonly name: string;
+    readonly value?: DataType;
+    readonly container?: {
+        [id: number]: IElementType;
+    };
+    readonly multiple?: boolean;
+}
+export interface IEbmlDoc {
+    ebml: IEbmlElements;
+}

package/lib/ebml/types.js

@@ -0,0 +1,10 @@
+export var DataType;
+(function (DataType) {
+    DataType[DataType["string"] = 0] = "string";
+    DataType[DataType["uint"] = 1] = "uint";
+    DataType[DataType["uid"] = 2] = "uid";
+    DataType[DataType["bool"] = 3] = "bool";
+    DataType[DataType["binary"] = 4] = "binary";
+    DataType[DataType["float"] = 5] = "float";
+})(DataType || (DataType = {}));
+//# sourceMappingURL=types.js.map

package/lib/id3v2/ID3v2Parser.js

@@ -54,17 +54,16 @@ export class ID3v2Parser {
         };
     }
     static readFrameData(uint8Array, frameHeader, majorVer, includeCovers, warningCollector) {
-        var _a, _b;
         const frameParser = new FrameParser(majorVer, warningCollector);
         switch (majorVer) {
             case 2:
                 return frameParser.readData(uint8Array, frameHeader.id, includeCovers);
             case 3:
             case 4:
-                if ((_a = frameHeader.flags) === null || _a === void 0 ? void 0 : _a.format.unsynchronisation) {
+                if (frameHeader.flags?.format.unsynchronisation) {
                     uint8Array = ID3v2Parser.removeUnsyncBytes(uint8Array);
                 }
-                if ((_b = frameHeader.flags) === null || _b === void 0 ? void 0 : _b.format.data_length_indicator) {
+                if (frameHeader.flags?.format.data_length_indicator) {
                     uint8Array = uint8Array.slice(4, uint8Array.length);
                 }
                 return frameParser.readData(uint8Array, frameHeader.id, includeCovers);

package/lib/matroska/MatroskaDtd.d.ts

@@ -1,8 +1,8 @@
-import { type IContainerType } from './types.js';
+import { type IElementType } from '../ebml/types.js';
 /**
  * Elements of document type description
  * Derived from https://github.com/tungol/EBML/blob/master/doctypes/matroska.dtd
  * Extended with:
  * - https://www.matroska.org/technical/specs/index.html
  */
-export declare const elements: IContainerType;
+export declare const matroskaDtd: IElementType;