music-metadata 12.2.0 → 12.2.2

package/README.md

@@ -177,6 +177,8 @@ parseFile(filePath: string, options?: IOptions): Promise<IAudioMetadata>
 
 - This function is **Node.js-only** and relies on Node.js-specific APIs to access the filesystem.
 
+- The path must resolve to a regular file. Symlinks to regular files are supported. Directories, FIFOs (named pipes), and other non-regular filesystem objects are rejected with `NotRegularFileError` from `strtok3`. FIFOs are rejected without waiting for a writer. To parse streamed audio, use [`parseStream()`](#parsestream-function).
+
 - For browser environments, consider using the [parseBlob](#parseblob-function) to parse [File object](https://developer.mozilla.org/en-US/docs/Web/API/File) objects.
 
 ##### Example:
@@ -618,6 +620,7 @@ Returns a list of supported MIME-types. This may include some MIME-types which a
   Maximum bytes buffered for a single metadata payload, accumulated Ogg packet, or tokenizer stream lookahead.
   Must be a positive safe integer. Parsing rejects payloads above this limit before allocating them.
   The parser configures this limit once on its `strtok3` tokenizers, including tokenizers for embedded tags.
+  The same limit applies to `file-type` read buffers when detecting the media format or a cover art MIME-type.
   Oversized tokenizer allocations or stream lookahead reject with `strtok3.BufferSizeError`.
   When using `parseFromTokenizer()`, also configure `maxBufferSize` on the supplied tokenizer at creation.
   Increase it for files with unusually large metadata or cover art, or lower it for constrained environments.
@@ -631,10 +634,17 @@ 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.
 
+  For large MKV files on network shares, use `parseFile(filePath, { mkvUseIndex: true })`
+  when the file's SeekHead index is reliable. The default traversal reads every cluster header,
+  so network latency can dominate even though the audio/video payloads are skipped.
+
 - `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.
+  The callback runs synchronously after the update; returned promises are not awaited.
+  Repeated assignments of unchanged primitive format values do not trigger callbacks.
+  Keep callback work lightweight, or batch expensive operations in the consuming application.
  
 - `skipCovers`: `boolean` (default: `false`)
 

package/lib/ParserFactory.d.ts

@@ -1,5 +1,5 @@
 import { type MediaType } from 'media-typer';
-import type { ITokenizer } from 'strtok3';
+import { type ITokenizer } from 'strtok3';
 import { type INativeMetadataCollector } from './common/MetadataCollector.js';
 import { type IAudioMetadata, type IOptions, type ParserType } from './type.js';
 export interface IParserLoader {

package/lib/ParserFactory.js

@@ -2,6 +2,7 @@ import { parse as parseContentType } from 'content-type';
 import initDebug from 'debug';
 import { fileTypeFromBuffer } from 'file-type';
 import { parse as mimeTypeParse } from 'media-typer';
+import { isRandomAccessTokenizer } from 'strtok3';
 import { aiffParserLoader } from './aiff/AiffLoader.js';
 import { apeParserLoader } from './apev2/Apev2Loader.js';
 import { asfParserLoader } from './asf/AsfLoader.js';
@@ -59,8 +60,8 @@ export class ParserFactory {
         this.parsers.push(parser);
     }
     async parse(tokenizer, parserLoader, opts = {}) {
-        getMaxMemoryAllocation(opts);
-        if (tokenizer.supportsRandomAccess()) {
+        const maxBufferSize = getMaxMemoryAllocation(opts);
+        if (isRandomAccessTokenizer(tokenizer)) {
             debug('tokenizer supports random-access, scanning for appending headers');
             await scanAppendingHeaders(tokenizer, opts);
         }
@@ -79,7 +80,7 @@ export class ParserFactory {
                 // Parser could not be determined on MIME-type or extension
                 debug('Guess parser on content...');
                 await tokenizer.peekBuffer(buf, { mayBeLess: true });
-                const guessedType = await fileTypeFromBuffer(buf, { mpegOffsetTolerance: 10 });
+                const guessedType = await fileTypeFromBuffer(buf, { mpegOffsetTolerance: 10, maxBufferSize });
                 if (!guessedType?.mime) {
                     throw new CouldNotDetermineFileTypeError('Failed to determine audio format');
                 }

package/lib/aiff/AiffParser.js

@@ -1,10 +1,9 @@
 import initDebug from 'debug';
 import * as strtok3 from 'strtok3';
 import * as Token from 'token-types';
-import { getTokenizerOptions } from '../common/Allocation.js';
 import { BasicParser } from '../common/BasicParser.js';
 import { FourCcToken } from '../common/FourCC.js';
-import { ID3v2Parser } from '../id3v2/ID3v2Parser.js';
+import { parseEmbeddedID3v2 } from '../id3v2/EmbeddedID3v2.js';
 import * as iff from '../iff/index.js';
 import * as AiffToken from './AiffToken.js';
 import { AiffContentError, compressionTypes } from './AiffToken.js';
@@ -77,9 +76,7 @@ export class AIFFParser extends BasicParser {
             }
             case 'ID3 ': {
                 // ID3-meta-data
-                const id3_data = await this.readToken(new Token.Uint8ArrayType(header.chunkSize));
-                const rst = strtok3.fromBuffer(id3_data, getTokenizerOptions(this.options));
-                await new ID3v2Parser().parse(this.metadata, rst, this.options);
+                await parseEmbeddedID3v2(this.metadata, this.tokenizer, this.options, header.chunkSize);
                 return header.chunkSize;
             }
             case 'SSND': // Sound Data Chunk

package/lib/common/Allocation.js

@@ -1,4 +1,4 @@
-import { EndOfStreamError } from 'strtok3';
+import { EndOfStreamError, isRandomAccessTokenizer } from 'strtok3';
 import { UnexpectedFileContentError } from '../ParseError.js';
 const defaultMaxMemoryAllocation = 64 * 1024 * 1024;
 const readChunkSize = 64 * 1024;
@@ -33,7 +33,7 @@ function validateAvailableBytes(tokenizer, length, position) {
 export async function readBuffer(tokenizer, length, options, position = tokenizer.position, makeError = allocationError) {
     validateAllocation(length, options, makeError);
     validateAvailableBytes(tokenizer, length, position);
-    if ((!tokenizer.supportsRandomAccess() || tokenizer.fileInfo.size === undefined) && length > readChunkSize) {
+    if (!isRandomAccessTokenizer(tokenizer) && length > readChunkSize) {
         const chunks = [];
         for (let remaining = length; remaining > 0;) {
             const chunk = new Uint8Array(Math.min(remaining, readChunkSize));

package/lib/common/CombinedTagMapper.js

@@ -18,7 +18,6 @@ export class CombinedTagMapper {
             new ID3v22TagMapper(),
             new ID3v24TagMapper(),
             new MP4TagMapper(),
-            new MP4TagMapper(),
             new VorbisTagMapper(),
             new APEv2TagMapper(),
             new AsfTagMapper(),

package/lib/common/MetadataCollector.d.ts

@@ -1,4 +1,4 @@
-import { type AnyTagValue, type FormatId, type IAudioMetadata, type ICommonTagsResult, type IFormat, type INativeTags, type IOptions, type IQualityInformation, type ITrackInfo } from '../type.js';
+import { type AnyTagValue, type IAudioMetadata, type ICommonTagsResult, type IFormat, type INativeTags, type IOptions, type IQualityInformation, type ITrackInfo } from '../type.js';
 import { type IGenericTag, type TagType } from './GenericTagTypes.js';
 /**
  * Combines all generic-tag-mappers for each tag type
@@ -21,15 +21,15 @@ export interface INativeMetadataCollector extends IWarningCollector {
      * @returns {boolean} true if one or more tags have been found
      */
     hasAny(): boolean;
-    setFormat(key: FormatId, value: AnyTagValue): void;
+    setFormat<K extends keyof IFormat>(key: K, value: IFormat[K]): void;
     registerTagType(tagType: TagType): void;
     addTag(tagType: TagType, tagId: string, value: AnyTagValue): Promise<void>;
     addStreamInfo(streamInfo: ITrackInfo): void;
     setAudioOnly(): void;
 }
 /**
- * Provided to the parser to uodate the metadata result.
- * Responsible for triggering async updates
+ * Provided to the parser to update the metadata result.
+ * Responsible for notifying observers synchronously after updates.
  */
 export declare class MetadataCollector implements INativeMetadataCollector {
     readonly format: IFormat;
@@ -52,7 +52,7 @@ export declare class MetadataCollector implements INativeMetadataCollector {
      */
     hasAny(): boolean;
     addStreamInfo(streamInfo: ITrackInfo): void;
-    setFormat(key: FormatId, value: AnyTagValue): void;
+    setFormat<K extends keyof IFormat>(key: K, value: IFormat[K]): void;
     setAudioOnly(): void;
     registerTagType(tagType: TagType): void;
     addTag(tagType: TagType, tagId: string, value: AnyTagValue): Promise<void>;

package/lib/common/MetadataCollector.js

@@ -2,6 +2,7 @@ import initDebug from 'debug';
 import { fileTypeFromBuffer } from 'file-type';
 import { parseLyrics } from '../lrc/LyricsParser.js';
 import { TrackTypeValueToKeyMap } from '../type.js';
+import { getMaxMemoryAllocation } from './Allocation.js';
 import { CombinedTagMapper } from './CombinedTagMapper.js';
 import { CommonTagMapper } from './GenericTagMapper.js';
 import { isSingleton, isUnique } from './GenericTagTypes.js';
@@ -23,8 +24,8 @@ const TagPriority = [
     'ID3v1'
 ];
 /**
- * Provided to the parser to uodate the metadata result.
- * Responsible for triggering async updates
+ * Provided to the parser to update the metadata result.
+ * Responsible for notifying observers synchronously after updates.
  */
 export class MetadataCollector {
     format = {
@@ -73,8 +74,13 @@ export class MetadataCollector {
         this.format.trackInfo.push(streamInfo);
     }
     setFormat(key, value) {
+        // Objects may have been mutated in place, so only skip unchanged primitives.
+        if ((value === null || typeof value !== 'object') && Object.is(this.format[key], value)) {
+            return;
+        }
         debug(`format: ${key} = ${value}`);
-        this.format[key] = value; // as any to override readonly
+        // Allow internal writes while preserving each property's value type.
+        this.format[key] = value;
         if (this.opts?.observer) {
             this.opts.observer({ metadata: this, tag: { type: 'format', id: key, value } });
         }
@@ -260,7 +266,9 @@ export class MetadataCollector {
     async postFixPicture(picture) {
         if (picture.data && picture.data.length > 0) {
             if (!picture.format) {
-                const fileType = await fileTypeFromBuffer(Uint8Array.from(picture.data)); // ToDO: remove Buffer
+                const fileType = await fileTypeFromBuffer(Uint8Array.from(picture.data), {
+                    maxBufferSize: getMaxMemoryAllocation(this.opts ?? {})
+                }); // ToDO: remove Buffer
                 if (fileType) {
                     picture.format = fileType.mime;
                 }

package/lib/dsdiff/DsdiffLoader.js

@@ -1,7 +1,7 @@
 export const dsdiffParserLoader = {
     parserType: 'dsdiff',
     extensions: ['.dff'],
-    mimeTypes: ['audio/dsf', 'audio/dsd'],
+    mimeTypes: ['audio/dsf', 'audio/dsd', 'audio/dff'],
     async load() {
         return (await import('./DsdiffParser.js')).DsdiffParser;
     }

package/lib/dsdiff/DsdiffParser.js

@@ -1,10 +1,8 @@
 import initDebug from 'debug';
-import * as strtok3 from 'strtok3';
 import * as Token from 'token-types';
-import { getTokenizerOptions } from '../common/Allocation.js';
 import { BasicParser } from '../common/BasicParser.js';
 import { FourCcToken } from '../common/FourCC.js';
-import { ID3v2Parser } from '../id3v2/ID3v2Parser.js';
+import { parseEmbeddedID3v2 } from '../id3v2/EmbeddedID3v2.js';
 import { makeUnexpectedFileContentError } from '../ParseError.js';
 import { ChunkHeader64 } from './DsdiffToken.js';
 const debug = initDebug('music-metadata:parser:dsdiff');
@@ -94,9 +92,7 @@ export class DsdiffParser extends BasicParser {
             }
             case 'ID3': {
                 // Unofficial ID3 tag support
-                const id3_data = await this.readToken(new Token.Uint8ArrayType(Number(header.chunkSize)));
-                const rst = strtok3.fromBuffer(id3_data, getTokenizerOptions(this.options));
-                await new ID3v2Parser().parse(this.metadata, rst, this.options);
+                await parseEmbeddedID3v2(this.metadata, this.tokenizer, this.options, Number(header.chunkSize));
                 break;
             }
             case 'DSD':

package/lib/dsf/DsfParser.js

@@ -64,7 +64,7 @@ export class DsfParser extends AbstractID3Parser {
                     this.metadata.setFormat('numberOfChannels', formatChunk.channelNum);
                     this.metadata.setFormat('sampleRate', formatChunk.samplingFrequency);
                     this.metadata.setFormat('bitsPerSample', formatChunk.bitsPerSample);
-                    this.metadata.setFormat('numberOfSamples', formatChunk.sampleCount);
+                    this.metadata.setFormat('numberOfSamples', Number(formatChunk.sampleCount));
                     this.metadata.setFormat('duration', Number(formatChunk.sampleCount) / formatChunk.samplingFrequency);
                     const bitrate = formatChunk.bitsPerSample * formatChunk.samplingFrequency * formatChunk.channelNum;
                     this.metadata.setFormat('bitrate', bitrate);

package/lib/ebml/EbmlIterator.d.ts

@@ -1,6 +1,6 @@
 import { type ITokenizer } from 'strtok3';
 import type { IOptions } from '../type.js';
-import { type IElementType, type ITree, type ValueType } from './types.js';
+import { type DecodedElement, type ElementEvent, type IElementContext, type IElementType, type ValueType } from './types.js';
 declare const EbmlContentError_base: {
     new (message: string): {
         message: string;
@@ -16,13 +16,8 @@ declare const EbmlContentError_base: {
 };
 export declare class EbmlContentError extends EbmlContentError_base {
 }
-export interface ILinkedElementType extends IElementType {
-    id: number;
-    parent: ILinkedElementType | undefined;
-    readonly container?: {
-        [id: number]: ILinkedElementType;
-    };
-}
+/** @deprecated Use the per-visit IElementContext instead. */
+export type ILinkedElementType = IElementContext;
 export declare const ParseAction: {
     readonly ReadNext: 0;
     readonly IgnoreElement: 2;
@@ -31,12 +26,19 @@ export declare const ParseAction: {
     readonly SkipElement: 5;
 };
 export type ParseAction = (typeof ParseAction)[keyof typeof ParseAction];
-/**
- * @return true, to quit the parser
- */
-export type IElementListener = {
-    startNext: (dtdElement: ILinkedElementType) => ParseAction;
-    elementValue: (dtdElement: ILinkedElementType, value: ValueType, offset: number) => Promise<void>;
+/** Traversal callbacks and optional subtree retention. */
+export type IElementListener<S extends IElementType = IElementType> = {
+    startNext: (element: IElementContext) => ParseAction | Promise<ParseAction>;
+    /** Legacy untyped events; new consumers should use onElement. */
+    elementValue?: (element: IElementContext, value: ValueType, offset: number) => Promise<void>;
+    onElement?: (event: ElementEvent<S>) => Promise<void>;
+    /**
+     * Collect only subtrees rooted at matching containers. Descendants of a selected
+     * container are retained until its event completes; other ancestors stay empty.
+     * Omit this callback to collect the entire document (legacy iterator behavior).
+     * Leaf events are delivered even when their values are not retained.
+     */
+    collect?: (element: IElementContext) => boolean;
 };
 /**
  * Extensible Binary Meta Language (EBML) iterator
@@ -51,19 +53,22 @@ export declare class EbmlIterator {
     private ebmlMaxIDLength;
     private ebmlMaxSizeLength;
     private tokenizer;
+    private readonly elementHeader;
     /**
      * @param {ITokenizer} tokenizer Input
      * @param tokenizer
      */
     constructor(tokenizer: ITokenizer, options?: IOptions);
-    iterate(dtdElement: IElementType, posDone: number, listener: IElementListener): Promise<ITree>;
+    iterate<const S extends IElementType>(dtdElement: S, posDone: number, listener: IElementListener<S>): Promise<DecodedElement<S>>;
     private parseContainer;
+    private collect;
     private ignore;
     private readVintData;
     private readElement;
     private readFloat;
     private readFlag;
     private readUint;
+    private readInt;
     private readString;
     private readBuffer;
 }

package/lib/ebml/EbmlIterator.js

@@ -1,8 +1,8 @@
 import initDebug from 'debug';
-import { EndOfStreamError } from 'strtok3';
+import { EndOfStreamError, isRandomAccessTokenizer } from 'strtok3';
 import * as Token from 'token-types';
 import { Float32_BE, Float64_BE, StringType, UINT8 } from 'token-types';
-import { readBuffer } from '../common/Allocation.js';
+import { getMaxMemoryAllocation, readBuffer } from '../common/Allocation.js';
 import { makeUnexpectedFileContentError } from '../ParseError.js';
 import { DataType } from './types.js';
 const debug = initDebug('music-metadata:parser:ebml');
@@ -28,6 +28,7 @@ export class EbmlIterator {
     ebmlMaxIDLength = 4;
     ebmlMaxSizeLength = 8;
     tokenizer;
+    elementHeader;
     /**
      * @param {ITokenizer} tokenizer Input
      * @param tokenizer
@@ -35,7 +36,9 @@ export class EbmlIterator {
     constructor(tokenizer, options = {}) {
         this.options = options;
         this.tokenizer = tokenizer;
+        this.elementHeader = new Uint8Array(Math.min(12, getMaxMemoryAllocation(options)));
         this.parserMap.set(DataType.uint, e => this.readUint(e));
+        this.parserMap.set(DataType.int, e => this.readInt(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));
@@ -43,9 +46,20 @@ export class EbmlIterator {
         this.parserMap.set(DataType.float, e => this.readFloat(e));
     }
     async iterate(dtdElement, posDone, listener) {
-        return this.parseContainer(linkParents(dtdElement), posDone, listener);
+        const root = { ...dtdElement, id: 0, parent: undefined };
+        const tree = await this.parseContainer(root, posDone, {
+            startNext: listener.startNext,
+            collect: listener.collect ?? (() => true),
+            elementValue: async (element, value, offset) => {
+                await listener.elementValue?.(element, value, offset);
+                // The schema selects both the decoder and the event ID. Keep this bridge here,
+                // rather than asserting unrelated domain types in each parser listener.
+                await listener.onElement?.({ id: element.id, element, value, offset });
+            }
+        }, listener.collect?.(root) ?? true);
+        return tree;
     }
-    async parseContainer(dtdElement, posDone, listener) {
+    async parseContainer(dtdElement, posDone, listener, collect) {
         const tree = {};
         while (this.tokenizer.position < posDone) {
             let element;
@@ -59,34 +73,24 @@ export class EbmlIterator {
                 }
                 throw error;
             }
-            const child = dtdElement.container[element.id];
-            if (child) {
-                const action = listener.startNext(child);
+            const definition = dtdElement.container?.[element.id];
+            if (definition) {
+                const child = { ...definition, id: element.id, parent: dtdElement };
+                const action = await 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 childEnd = Math.min(posDone, this.tokenizer.fileInfo.size ?? Number.POSITIVE_INFINITY, element.len >= 0 ? this.tokenizer.position + element.len : posDone);
-                                const res = await this.parseContainer(child, childEnd, listener);
-                                if (child.multiple) {
-                                    if (!tree[child.name]) {
-                                        tree[child.name] = [];
-                                    }
-                                    tree[child.name].push(res);
-                                }
-                                else {
-                                    tree[child.name] = res;
+                                const res = await this.parseContainer(child, childEnd, listener, collect || listener.collect(child));
+                                if (collect) {
+                                    this.collect(tree, child, res);
                                 }
                                 await listener.elementValue(child, res, elementPosition);
                             }
                             else {
-                                const parser = this.parserMap.get(child.value);
+                                const parser = child.value === undefined ? undefined : this.parserMap.get(child.value);
                                 if (typeof parser === 'function') {
                                     // Validate before leaf readers allocate buffers or string tokens from the declared length.
                                     const end = Math.min(posDone, this.tokenizer.fileInfo.size ?? Number.POSITIVE_INFINITY);
@@ -96,9 +100,14 @@ export class EbmlIterator {
                                         throw new EbmlContentError(`Invalid element length: ${element.len}`);
                                     }
                                     const value = await parser(element);
-                                    tree[child.name] = value;
+                                    if (collect) {
+                                        this.collect(tree, child, value);
+                                    }
                                     await listener.elementValue(child, value, elementPosition);
                                 }
+                                else {
+                                    await this.ignore(element.len, posDone);
+                                }
                             }
                         }
                         break;
@@ -131,6 +140,17 @@ export class EbmlIterator {
         }
         return tree;
     }
+    collect(tree, element, value) {
+        if (element.multiple) {
+            const values = (tree[element.name] ??= []);
+            if (Array.isArray(values)) {
+                values.push(value);
+            }
+        }
+        else {
+            tree[element.name] = value;
+        }
+    }
     async ignore(length, posDone) {
         // Unknown-size EBML containers may advertise lengths above the safe integer range.
         // Bound skips by the enclosing container and known input before passing them to the tokenizer.
@@ -158,6 +178,33 @@ export class EbmlIterator {
         return id;
     }
     async readElement() {
+        if (isRandomAccessTokenizer(this.tokenizer) && this.elementHeader.length === 12) {
+            // RFC 8794 (July 2020), sections 4-6: an ID and size occupy at most 4 + 8 bytes.
+            // Peek both VINTs together to avoid four separate file/network reads per element.
+            // https://www.rfc-editor.org/rfc/rfc8794.html#section-4
+            const available = await this.tokenizer.peekBuffer(this.elementHeader, { mayBeLess: true });
+            const width = (offset, maximum) => {
+                if (offset >= available) {
+                    throw new EndOfStreamError();
+                }
+                for (let length = 1; length <= maximum; ++length) {
+                    if ((this.elementHeader[offset] & (0x80 >> (length - 1))) !== 0) {
+                        if (offset + length > available) {
+                            throw new EndOfStreamError();
+                        }
+                        return length;
+                    }
+                }
+                throw new EbmlContentError('VINT value exceeding maximum size');
+            };
+            const idLength = width(0, this.ebmlMaxIDLength);
+            const sizeLength = width(idLength, this.ebmlMaxSizeLength);
+            const id = readUIntBE(this.elementHeader.subarray(0, idLength), idLength);
+            const lenField = this.elementHeader.subarray(idLength, idLength + sizeLength);
+            lenField[0] ^= 0x80 >> (sizeLength - 1);
+            this.tokenizer.setPosition(this.tokenizer.position + idLength + sizeLength);
+            return { id, len: readUIntBE(lenField, sizeLength) };
+        }
         const id = await this.readVintData(this.ebmlMaxIDLength);
         const lenField = await this.readVintData(this.ebmlMaxSizeLength);
         lenField[0] ^= 0x80 >> (lenField.length - 1);
@@ -187,6 +234,11 @@ export class EbmlIterator {
         const buf = await this.readBuffer(e);
         return readUIntBE(buf, e.len);
     }
+    async readInt(e) {
+        const buffer = await this.readBuffer(e);
+        const value = readUIntBeAsBigInt(buffer, e.len);
+        return Number(buffer[0] & 0x80 ? value - (1n << BigInt(8 * e.len)) : value);
+    }
     async readString(e) {
         const buf = await this.readBuffer(e);
         const rawString = new StringType(e.len, 'utf-8').get(buf, 0);
@@ -216,21 +268,6 @@ function readUIntBeAsBigInt(buf, len) {
         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, 10);
-            return child;
-        })
-            .forEach(child => {
-            child.parent = element;
-            linkParents(child);
-        });
-    }
-    return element;
-}
 export function getElementPath(element) {
     let path = '';
     if (element.parent && element.parent.name !== 'dtd') {

package/lib/ebml/types.d.ts

@@ -1,5 +1,6 @@
+export type PrimitiveValue = string | number | boolean | Uint8Array;
 export interface ITree {
-    [name: string]: string | number | boolean | Uint8Array | ITree | ITree[];
+    [name: string]: PrimitiveValue | ITree | (PrimitiveValue | ITree)[];
 }
 export declare const DataType: {
     readonly string: 0;
@@ -8,18 +9,19 @@ export declare const DataType: {
     readonly bool: 3;
     readonly binary: 4;
     readonly float: 5;
+    readonly int: 6;
 };
 export type DataType = (typeof DataType)[keyof typeof DataType];
-export type ValueType = string | number | Uint8Array | boolean | ITree | ITree[];
+export type ValueType = PrimitiveValue | ITree;
 export interface IHeader {
     id: number;
     len: number;
 }
 export interface IEbmlElements {
-    version?: number;
-    readVersion?: number;
-    maxIDWidth?: number;
-    maxSizeWidth?: number;
+    ebmlVersion?: number;
+    ebmlReadVersion?: number;
+    ebmlMaxIDWidth?: number;
+    ebmlMaxSizeWidth?: number;
     docType?: string;
     docTypeVersion?: number;
     docTypeReadVersion?: number;
@@ -28,10 +30,36 @@ export interface IElementType {
     readonly name: string;
     readonly value?: DataType;
     readonly container?: {
-        [id: number]: IElementType;
+        readonly [id: number]: IElementType;
     };
     readonly multiple?: boolean;
 }
 export interface IEbmlDoc {
-    ebml: IEbmlElements;
+    ebml?: IEbmlElements;
 }
+/** Values reflect what was actually read: even required EBML elements can be absent or skipped. */
+export type DecodedElement<S extends IElementType> = S extends {
+    readonly container: infer C extends Readonly<Record<number, IElementType>>;
+} ? {
+    -readonly [E in C[keyof C & number] as E['name']]?: E extends {
+        readonly multiple: true;
+    } ? DecodedElement<E>[] : DecodedElement<E>;
+} : S extends {
+    readonly value: infer V extends DataType;
+} ? V extends typeof DataType.string ? string : V extends typeof DataType.bool ? boolean : V extends typeof DataType.binary | typeof DataType.uid ? Uint8Array : number : ITree;
+/** Per-visit context; the schema itself never gains IDs or parent links. */
+export interface IElementContext extends IElementType {
+    readonly id: number;
+    readonly parent: IElementContext | undefined;
+}
+/** Discriminating by ID narrows the decoded value along with the element. */
+export type ElementEvent<S extends IElementType> = S extends {
+    readonly container: infer C extends Readonly<Record<number, IElementType>>;
+} ? {
+    [Id in keyof C & number]: {
+        id: Id;
+        element: IElementContext;
+        value: DecodedElement<C[Id]>;
+        offset: number;
+    } | ElementEvent<C[Id]>;
+}[keyof C & number] : never;

package/lib/ebml/types.js

@@ -4,5 +4,6 @@ export const DataType = {
     uid: 2,
     bool: 3,
     binary: 4,
-    float: 5
+    float: 5,
+    int: 6
 };

package/lib/flac/FlacParser.js

@@ -92,24 +92,16 @@ export class FlacParser extends AbstractID3Parser {
      */
     async parseComment(data) {
         const decoder = new VorbisDecoder(data, 0);
-        const vendor = decoder.readStringUtf8();
+        const { vendor, comments } = decoder.parseCommentList(message => new FlacContentError(message));
         if (vendor.length > 0) {
             this.metadata.setFormat('tool', vendor);
         }
-        const commentListLength = decoder.readInt32();
-        if (commentListLength > Math.floor(decoder.remaining / 4)) {
-            throw new FlacContentError(`Vorbis comment count ${commentListLength} exceeds remaining data`);
-        }
-        const tags = [];
-        for (let i = 0; i < commentListLength; i++) {
-            tags.push(decoder.parseUserComment());
-        }
-        await Promise.all(tags.map(tag => {
+        for (const tag of comments) {
             if (tag.key === 'ENCODER') {
                 this.metadata.setFormat('tool', tag.value);
             }
-            return this.addTag(tag.key, tag.value);
-        }));
+            await this.addTag(tag.key, tag.value);
+        }
     }
     async parsePicture(dataLen) {
         if (this.options.skipCovers) {

package/lib/id3v1/ID3v1Parser.d.ts

@@ -1,4 +1,4 @@
-import type { IRandomAccessTokenizer, ITokenizer } from 'strtok3';
+import { type IRandomAccessTokenizer, type ITokenizer } from 'strtok3';
 import { BasicParser } from '../common/BasicParser.js';
 import type { INativeMetadataCollector } from '../common/MetadataCollector.js';
 import type { IPrivateOptions } from '../type.js';

package/lib/id3v1/ID3v1Parser.js

@@ -1,5 +1,6 @@
 import { textDecode } from '@borewit/text-codec';
 import initDebug from 'debug';
+import { isRandomAccessTokenizer } from 'strtok3';
 import { StringType, UINT8 } from 'token-types';
 import { APEv2Parser } from '../apev2/APEv2Parser.js';
 import { BasicParser } from '../common/BasicParser.js';
@@ -266,7 +267,7 @@ export class ID3v1Parser extends BasicParser {
             debug('Skip checking for ID3v1 because the file-size is unknown');
             return;
         }
-        if (this.apeHeader && this.tokenizer.supportsRandomAccess()) {
+        if (this.apeHeader && isRandomAccessTokenizer(this.tokenizer)) {
             this.tokenizer.setPosition(this.apeHeader.offset);
             const apeParser = new APEv2Parser(this.metadata, this.tokenizer, this.options);
             await apeParser.parseTags(this.apeHeader.footer);