music-metadata 12.2.0 → 12.2.1

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:
@@ -631,6 +633,10 @@ 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.

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/ebml/EbmlIterator.d.ts

@@ -51,6 +51,7 @@ export declare class EbmlIterator {
     private ebmlMaxIDLength;
     private ebmlMaxSizeLength;
     private tokenizer;
+    private readonly elementHeader;
     /**
      * @param {ITokenizer} tokenizer Input
      * @param tokenizer

package/lib/ebml/EbmlIterator.js

@@ -2,7 +2,7 @@ import initDebug from 'debug';
 import { EndOfStreamError } 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,6 +36,7 @@ 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.string, e => this.readString(e));
         this.parserMap.set(DataType.binary, e => this.readBuffer(e));
@@ -158,6 +160,33 @@ export class EbmlIterator {
         return id;
     }
     async readElement() {
+        if (this.tokenizer.supportsRandomAccess() && 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);

package/lib/index.d.ts

@@ -15,8 +15,10 @@ export * from './core.js';
 export declare function parseStream(stream: Readable, fileInfo?: IFileInfo | string, options?: IOptions): Promise<IAudioMetadata>;
 /**
  * Parse audio from Node file
+ * Requires a regular file; symlinks to regular files are supported.
  * @param filePath - Media file to read meta-data from
  * @param options - Parsing options
  * @returns Metadata
+ * @throws {NotRegularFileError} If the opened filesystem object is not a regular file.
  */
 export declare function parseFile(filePath: string, options?: IOptions): Promise<IAudioMetadata>;

package/lib/index.js

@@ -26,13 +26,18 @@ export async function parseStream(stream, fileInfo, options = {}) {
 }
 /**
  * Parse audio from Node file
+ * Requires a regular file; symlinks to regular files are supported.
  * @param filePath - Media file to read meta-data from
  * @param options - Parsing options
  * @returns Metadata
+ * @throws {NotRegularFileError} If the opened filesystem object is not a regular file.
  */
 export async function parseFile(filePath, options = {}) {
     debug(`parseFile: ${filePath}`);
-    const fileTokenizer = await fromFile(filePath, getTokenizerOptions(options));
+    const fileTokenizer = await fromFile(filePath, {
+        ...getTokenizerOptions(options),
+        regularFileOnly: true
+    });
     const parserFactory = new ParserFactory();
     try {
         const parserLoader = parserFactory.findLoaderForExtension(filePath);

package/lib/mp4/MP4Parser.js

@@ -626,7 +626,13 @@ export class MP4Parser extends BasicParser {
                 case 'tkhd': // TrackHeaderBox
                     track.header = await this.readToken(new AtomToken.TrackHeaderAtom(payLoadLength));
                     break;
-                case 'hdlr': // TrackHeaderBox
+                case 'hdlr': // Media handler; metadata and data handlers do not identify the track type.
+                    // QuickTime File Format, Media atom: Handler reference atom ('hdlr').
+                    // https://developer.apple.com/documentation/quicktime-file-format/media_atom/handler_reference_atom
+                    if (child.parent?.header.name !== 'mdia' || child.parent.parent !== trakBox) {
+                        await this.tokenizer.ignore(payLoadLength);
+                        break;
+                    }
                     track.handler = await this.readToken(new AtomToken.HandlerBox(payLoadLength));
                     if (track.handler.handlerType === 'audi' || track.handler.handlerType === 'soun') {
                         this.hasAudioTrack = true;

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": "12.2.0",
+  "version": "12.2.1",
   "author": {
     "name": "Borewit",
     "url": "https://github.com/Borewit"
@@ -122,9 +122,9 @@
     "@tokenizer/token": "^0.3.0",
     "content-type": "^3.1.1",
     "debug": "^4.4.3",
-    "file-type": "^22.1.1",
+    "file-type": "^22.2.0",
     "media-typer": "^2.0.0",
-    "strtok3": "^10.4.1",
+    "strtok3": "^10.5.0",
     "token-types": "^6.1.2",
     "uint8array-extras": "^1.6.0",
     "win-guid": "^0.2.1"
@@ -136,7 +136,7 @@
     "@types/debug": "^4.1.13",
     "@types/media-typer": "^1.1.3",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "c8": "^12.0.0",
     "chai": "^6.3.0",
     "chai-as-promised": "^8.0.2",