music-metadata 10.1.0 → 10.2.0

package/lib/matroska/MatroskaParser.js

@@ -1,10 +1,8 @@
-import { Float32_BE, Float64_BE, StringType, UINT8 } from 'token-types';
 import initDebug from 'debug';
-import { EndOfStreamError } from 'strtok3';
 import { BasicParser } from '../common/BasicParser.js';
-import * as matroskaDtd from './MatroskaDtd.js';
-import { DataType, TargetType, TrackType } from './types.js';
-import * as Token from 'token-types';
+import { matroskaDtd } from './MatroskaDtd.js';
+import { TargetType, TrackType } from './types.js';
+import { EbmlIterator, ParseAction } from '../ebml/EbmlIterator.js';
 const debug = initDebug('music-metadata:parser:matroska');
 /**
  * Extensible Binary Meta Language (EBML) parser
@@ -15,17 +13,13 @@ const debug = initDebug('music-metadata:parser:matroska');
  */
 export class MatroskaParser extends BasicParser {
     constructor() {
-        super();
-        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));
+        super(...arguments);
+        this.seekHeadOffset = 0;
+        /**
+         * Use index to skip multiple segment/cluster elements at once.
+         * Significant performance impact
+         */
+        this.flagUseIndexToSkipClusters = false;
     }
     /**
      * Initialize parser with output (metadata), input (tokenizer) & parsing options (options).
@@ -35,206 +29,127 @@ export class MatroskaParser extends BasicParser {
      */
     init(metadata, tokenizer, options) {
         super.init(metadata, tokenizer, options);
+        this.flagUseIndexToSkipClusters = options.mkvUseIndex ?? false;
         return this;
     }
     async parse() {
-        var _a;
-        const containerSize = (_a = this.tokenizer.fileInfo.size) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER;
-        const matroska = await this.parseContainer(matroskaDtd.elements, containerSize, []);
-        this.metadata.setFormat('container', `EBML/${matroska.ebml.docType}`);
-        if (matroska.segment) {
-            const info = matroska.segment.info;
-            if (info) {
-                const timecodeScale = info.timecodeScale ? info.timecodeScale : 1000000;
-                if (typeof info.duration === 'number') {
-                    const duration = info.duration * timecodeScale / 1000000000;
-                    await this.addTag('segment:title', info.title);
-                    this.metadata.setFormat('duration', Number(duration));
-                }
-            }
-            const audioTracks = matroska.segment.tracks;
-            if (audioTracks === null || audioTracks === void 0 ? void 0 : audioTracks.entries) {
-                audioTracks.entries.forEach(entry => {
-                    const stream = {
-                        codecName: entry.codecID.replace('A_', '').replace('V_', ''),
-                        codecSettings: entry.codecSettings,
-                        flagDefault: entry.flagDefault,
-                        flagLacing: entry.flagLacing,
-                        flagEnabled: entry.flagEnabled,
-                        language: entry.language,
-                        name: entry.name,
-                        type: entry.trackType,
-                        audio: entry.audio,
-                        video: entry.video
-                    };
-                    this.metadata.addStreamInfo(stream);
-                });
-                const audioTrack = audioTracks.entries
-                    .filter(entry => entry.trackType === TrackType.audio)
-                    .reduce((acc, cur) => {
-                    if (!acc)
-                        return cur;
-                    if (cur.flagDefault && !acc.flagDefault)
-                        return cur;
-                    if (cur.trackNumber < acc.trackNumber)
-                        return cur;
-                    return acc;
-                }, null);
-                if (audioTrack) {
-                    this.metadata.setFormat('codec', audioTrack.codecID.replace('A_', ''));
-                    this.metadata.setFormat('sampleRate', audioTrack.audio.samplingFrequency);
-                    this.metadata.setFormat('numberOfChannels', audioTrack.audio.channels);
-                }
-                if (matroska.segment.tags) {
-                    await Promise.all(matroska.segment.tags.tag.map(async (tag) => {
-                        const target = tag.target;
-                        const targetType = (target === null || target === void 0 ? void 0 : target.targetTypeValue) ? TargetType[target.targetTypeValue] : ((target === null || target === void 0 ? void 0 : target.targetType) ? target.targetType : 'track');
-                        await Promise.all(tag.simpleTags.map(async (simpleTag) => {
-                            const value = simpleTag.string ? simpleTag.string : simpleTag.binary;
-                            await this.addTag(`${targetType}:${simpleTag.name}`, value);
-                        }));
-                    }));
-                }
-                if (matroska.segment.attachments) {
-                    await Promise.all(matroska.segment.attachments.attachedFiles
-                        .filter(file => file.mimeType.startsWith('image/'))
-                        .map(file => this.addTag('picture', {
-                        data: file.data,
-                        format: file.mimeType,
-                        description: file.description,
-                        name: file.name
-                    })));
-                }
-            }
-        }
-    }
-    async parseContainer(container, posDone, path) {
-        const tree = {};
-        while (this.tokenizer.position < posDone) {
-            let element;
-            try {
-                element = await this.readElement();
-            }
-            catch (error) {
-                if (error instanceof EndOfStreamError) {
-                    break;
-                }
-                throw error;
-            }
-            const type = container[element.id];
-            if (type) {
-                debug(`Element: name=${type.name}, container=${!!type.container}`);
-                if (type.container) {
-                    const res = await this.parseContainer(type.container, element.len >= 0 ? this.tokenizer.position + element.len : -1, path.concat([type.name]));
-                    if (type.multiple) {
-                        if (!tree[type.name]) {
-                            tree[type.name] = [];
+        const containerSize = this.tokenizer.fileInfo.size ?? Number.MAX_SAFE_INTEGER;
+        const matroskaIterator = new EbmlIterator(this.tokenizer);
+        debug('Initializing DTD end MatroskaIterator');
+        await matroskaIterator.iterate(matroskaDtd, containerSize, {
+            startNext: (element) => {
+                switch (element.id) {
+                    // case 0x1f43b675: // cluster
+                    case 0x1c53bb6b: // Cueing Data
+                        debug(`Skip element: name=${element.name}, id=0x${element.id.toString(16)}`);
+                        return ParseAction.IgnoreElement;
+                    case 0x1f43b675: // cluster
+                        if (this.flagUseIndexToSkipClusters && this.seekHead) {
+                            const index = this.seekHead.seek.find(index => index.position + this.seekHeadOffset > this.tokenizer.position);
+                            if (index) {
+                                // Go to next index position
+                                const ignoreSize = index.position + this.seekHeadOffset - this.tokenizer.position;
+                                debug(`Use index to go to next position, ignoring ${ignoreSize} bytes`);
+                                this.tokenizer.ignore(ignoreSize);
+                                return ParseAction.SkipElement;
+                            }
                         }
-                        tree[type.name].push(res);
-                    }
-                    else {
-                        tree[type.name] = res;
-                    }
-                }
-                else {
-                    const parser = this.parserMap.get(type.value);
-                    if (typeof parser === 'function') {
-                        tree[type.name] = await parser(element);
-                    }
+                        return ParseAction.IgnoreElement;
+                    default:
+                        return ParseAction.ReadNext;
                 }
-            }
-            else {
+            },
+            elementValue: async (element, value, offset) => {
+                debug(`Received: name=${element.name}, value=${value}`);
                 switch (element.id) {
-                    case 0xec: // void
-                        this.padding += element.len;
-                        await this.tokenizer.ignore(element.len);
+                    case 0x4282: // docType
+                        this.metadata.setFormat('container', `EBML/${value}`);
+                        break;
+                    case 0x114d9b74:
+                        this.seekHead = value;
+                        this.seekHeadOffset = offset;
+                        break;
+                    case 0x1549a966:
+                        { // Info (Segment Information)
+                            const info = value;
+                            const timecodeScale = info.timecodeScale ? info.timecodeScale : 1000000;
+                            if (typeof info.duration === 'number') {
+                                const duration = info.duration * timecodeScale / 1000000000;
+                                await this.addTag('segment:title', info.title);
+                                this.metadata.setFormat('duration', Number(duration));
+                            }
+                        }
+                        break;
+                    case 0x1654ae6b:
+                        { // tracks
+                            const audioTracks = value;
+                            if (audioTracks?.entries) {
+                                audioTracks.entries.forEach(entry => {
+                                    const stream = {
+                                        codecName: entry.codecID.replace('A_', '').replace('V_', ''),
+                                        codecSettings: entry.codecSettings,
+                                        flagDefault: entry.flagDefault,
+                                        flagLacing: entry.flagLacing,
+                                        flagEnabled: entry.flagEnabled,
+                                        language: entry.language,
+                                        name: entry.name,
+                                        type: entry.trackType,
+                                        audio: entry.audio,
+                                        video: entry.video
+                                    };
+                                    this.metadata.addStreamInfo(stream);
+                                });
+                                const audioTrack = audioTracks.entries
+                                    .filter(entry => entry.trackType === TrackType.audio)
+                                    .reduce((acc, cur) => {
+                                    if (!acc)
+                                        return cur;
+                                    if (cur.flagDefault && !acc.flagDefault)
+                                        return cur;
+                                    if (cur.trackNumber < acc.trackNumber)
+                                        return cur;
+                                    return acc;
+                                }, null);
+                                if (audioTrack) {
+                                    this.metadata.setFormat('codec', audioTrack.codecID.replace('A_', ''));
+                                    this.metadata.setFormat('sampleRate', audioTrack.audio.samplingFrequency);
+                                    this.metadata.setFormat('numberOfChannels', audioTrack.audio.channels);
+                                }
+                            }
+                        }
+                        break;
+                    case 0x1254c367:
+                        { // tags
+                            const tags = value;
+                            await Promise.all(tags.tag.map(async (tag) => {
+                                const target = tag.target;
+                                const targetType = target?.targetTypeValue ? TargetType[target.targetTypeValue] : (target?.targetType ? target.targetType : 'track');
+                                await Promise.all(tag.simpleTags.map(async (simpleTag) => {
+                                    const value = simpleTag.string ? simpleTag.string : simpleTag.binary;
+                                    await this.addTag(`${targetType}:${simpleTag.name}`, value);
+                                }));
+                            }));
+                        }
+                        break;
+                    case 0x1941a469:
+                        { // attachments
+                            const attachments = value;
+                            await Promise.all(attachments.attachedFiles
+                                .filter(file => file.mimeType.startsWith('image/'))
+                                .map(file => this.addTag('picture', {
+                                data: file.data,
+                                format: file.mimeType,
+                                description: file.description,
+                                name: file.name
+                            })));
+                        }
                         break;
-                    default:
-                        debug(`parseEbml: path=${path.join('/')}, unknown element: id=${element.id.toString(16)}`);
-                        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: MatroskaParser.readUIntBE(id, id.length),
-            len: MatroskaParser.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 MatroskaParser.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;
+        });
     }
     async addTag(tagId, value) {
         await this.metadata.addTag('matroska', tagId, value);
     }
-    static readUIntBE(buf, len) {
-        return Number(MatroskaParser.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
-     */
-    static 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);
-        }
-    }
 }
 //# sourceMappingURL=MatroskaParser.js.map

package/lib/matroska/types.d.ts

@@ -1,34 +1,10 @@
-export interface IHeader {
-    id: number;
-    len: number;
-}
-export declare enum DataType {
-    'string' = 0,
-    uint = 1,
-    uid = 2,
-    bool = 3,
-    binary = 4,
-    float = 5
-}
-export interface IElementType<T> {
-    readonly name: string;
-    readonly value?: DataType;
-    readonly container?: IContainerType;
-    readonly multiple?: boolean;
-}
-export interface IContainerType {
-    [id: number]: IElementType<string | number | boolean | Uint8Array>;
-}
-export interface ITree {
-    [name: string]: string | number | boolean | Uint8Array | ITree | ITree[];
-}
-export type ValueType = string | number | Uint8Array | boolean | ITree | ITree[];
-export interface ISeekHead {
-    id?: Uint8Array;
-    position?: number;
+import type { IEbmlDoc } from '../ebml/types.js';
+export interface ISeek {
+    id: Uint8Array;
+    position: number;
 }
-export interface IMetaSeekInformation {
-    seekHeads: ISeekHead[];
+export interface ISeekHead {
+    seek: ISeek[];
 }
 export interface ISegmentInformation {
     uid?: Uint8Array;
@@ -151,26 +127,14 @@ export interface IAttachments {
     attachedFiles: IAttachmedFile[];
 }
 export interface IMatroskaSegment {
-    metaSeekInfo?: IMetaSeekInformation;
-    seekHeads?: ISeekHead[];
+    metaSeekInfo?: ISeekHead;
+    seekHeads?: ISeek[];
     info?: ISegmentInformation;
     tracks?: ITrackElement;
     tags?: ITags;
     cues?: ICuePoint[];
     attachments?: IAttachments;
 }
-export interface IEbmlElements {
-    version?: number;
-    readVersion?: number;
-    maxIDWidth?: number;
-    maxSizeWidth?: number;
-    docType?: string;
-    docTypeVersion?: number;
-    docTypeReadVersion?: number;
-}
-export interface IEbmlDoc {
-    ebml: IEbmlElements;
-}
 export interface IMatroskaDoc extends IEbmlDoc {
     segment: IMatroskaSegment;
 }

package/lib/matroska/types.js

@@ -1,12 +1,3 @@
-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 = {}));
 export var TargetType;
 (function (TargetType) {
     TargetType[TargetType["shot"] = 10] = "shot";

package/lib/type.d.ts

@@ -544,6 +544,15 @@ export interface IOptions {
      * Set observer for async callbacks to common or format.
      */
     observer?: Observer;
+    /**
+     * In Matroska based files, use the  _SeekHead_ element index to skip _segment/cluster_ elements.
+     * By default, disabled
+     * 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
+     * Ref: https://www.matroska.org/technical/diagram.html
+     */
+    mkvUseIndex?: boolean;
 }
 export interface IApeHeader extends IOptions {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "music-metadata",
   "description": "Music metadata parser for Node.js, supporting virtual any audio and tag format.",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "author": {
     "name": "Borewit",
     "url": "https://github.com/Borewit"
@@ -85,7 +85,7 @@
     "compile-doc": "tsc -p doc-gen",
     "compile": "yarn run  compile-src && yarn compile-test && yarn compile-doc",
     "lint-ts": "biome check",
-    "lint-md": "yarn run remark -u preset-lint-markdown-style-guide .",
+    "lint-md": "yarn run remark -u remark-preset-lint-consistent .",
     "lint": "yarn run lint-ts && yarn run lint-md",
     "test": "mocha",
     "build": "yarn run clean && yarn compile && yarn run doc-gen",
@@ -97,9 +97,9 @@
     "@tokenizer/token": "^0.3.0",
     "content-type": "^1.0.5",
     "debug": "^4.3.4",
-    "file-type": "^19.4.0",
+    "file-type": "^19.4.1",
     "media-typer": "^1.1.0",
-    "strtok3": "^8.0.5",
+    "strtok3": "^8.1.0",
     "token-types": "^6.0.0",
     "uint8array-extras": "^1.4.0"
   },
@@ -111,7 +111,7 @@
     "@types/debug": "^4.1.12",
     "@types/media-typer": "^1.1.3",
     "@types/mocha": "^10.0.7",
-    "@types/node": "^22.2.0",
+    "@types/node": "^22.3.0",
     "c8": "^10.1.2",
     "chai": "^5.1.1",
     "chai-as-promised": "^8.0.0",
@@ -120,7 +120,7 @@
     "mocha": "^10.7.3",
     "prettier": "^3.3.3",
     "remark-cli": "^12.0.1",
-    "remark-preset-lint-markdown-style-guide": "^6.0.0",
+    "remark-preset-lint-consistent": "^6.0.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.3"
   },