music-metadata 12.2.0 → 12.2.2

package/lib/mp4/MP4Parser.js

@@ -75,6 +75,10 @@ const encoderDict = {
 function distinct(value, index, self) {
     return self.indexOf(value) === index;
 }
+/** Chapter offsets can be revisited even when the total input size is unknown. */
+function supportsSeeking(tokenizer) {
+    return tokenizer.supportsRandomAccess() && 'setPosition' in tokenizer && typeof tokenizer.setPosition === 'function';
+}
 /**
  * Determine if a track carries audio.
  *
@@ -173,7 +177,7 @@ export class MP4Parser extends BasicParser {
             const rootAtom = await Atom.readAtom(this.tokenizer, (atom, remaining) => this.handleAtom(atom, remaining), null, remainingFileSize);
             remainingFileSize = rootAtom.header.length === 0n ? 0 : remainingFileSize - Number(rootAtom.header.length);
         }
-        if (this.mediaDataRanges.length > 0) {
+        if (this.mediaDataRanges.length > 0 && supportsSeeking(this.tokenizer)) {
             // Track references and sample tables may follow the media data in a trailing moov box.
             const tokenizer = this.tokenizer;
             const position = tokenizer.position;
@@ -626,7 +630,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;
@@ -782,7 +792,7 @@ export class MP4Parser extends BasicParser {
         mdat: async (len) => {
             const range = { offset: this.tokenizer.position, end: this.tokenizer.position + len };
             if (this.options.includeChapters) {
-                if (this.tokenizer.supportsRandomAccess()) {
+                if (supportsSeeking(this.tokenizer)) {
                     this.mediaDataRanges.push(range);
                 }
                 else {

package/lib/mpeg/MpegParser.js

@@ -160,7 +160,7 @@ export class MpegParser extends AbstractID3Parser {
         this.metadata.setFormat('container', header.container);
         this.metadata.setFormat('codec', header.codec);
         this.metadata.setFormat('lossless', false);
-        this.metadata.setFormat('sampleRate', header.samplingRate);
+        this.metadata.setFormat('sampleRate', header.samplingRate ?? undefined);
         this.frameCount++;
         return header instanceof AdtsFrameHeader ? this.parseAdts(header) : this.parseMpegFrame(header);
     }
@@ -301,7 +301,7 @@ export class MpegParser extends AbstractID3Parser {
         if (infoTag.lame) {
             this.metadata.setFormat('tool', `LAME ${common.stripNulls(infoTag.lame.version)}`);
             if (infoTag.lame.extended) {
-                this.metadata.setFormat('trackPeakLevel', infoTag.lame.extended.track_peak);
+                this.metadata.setFormat('trackPeakLevel', infoTag.lame.extended.track_peak ?? undefined);
                 if (infoTag.lame.extended.track_gain) {
                     this.metadata.setFormat('trackGain', infoTag.lame.extended.track_gain.adjustment);
                 }

package/lib/ogg/OggStreamMetadata.d.ts

@@ -1,13 +1,13 @@
 import type { TagType } from '../common/GenericTagTypes.js';
 import { type INativeMetadataCollector, MetadataCollector } from '../common/MetadataCollector.js';
-import type { AnyTagValue, FormatId, INativeTags, IQualityInformation } from '../type.js';
+import type { AnyTagValue, IFormat, INativeTags, IQualityInformation } from '../type.js';
 /** Keep format values local to a logical stream while sharing tags and warnings. */
 export declare class OggStreamMetadata extends MetadataCollector {
     private readonly parent;
     readonly native: INativeTags;
     readonly quality: IQualityInformation;
     constructor(parent: INativeMetadataCollector);
-    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>;
     addWarning(warning: string): void;

package/lib/ogg/vorbis/VorbisDecoder.d.ts

@@ -5,6 +5,16 @@ export declare class VorbisDecoder {
     get remaining(): number;
     readInt32(): number;
     readStringUtf8(): string;
+    /** Decode the shared structure, leaving packet framing and metadata policy to callers. */
+    parseCommentList(createCountError?: (message: string) => Error): {
+        vendor: string;
+        comments: Generator<{
+            key: string;
+            value: string;
+            len: number;
+        }, void, unknown>;
+    };
+    private parseUserCommentList;
     parseUserComment(): {
         key: string;
         value: string;

package/lib/ogg/vorbis/VorbisDecoder.js

@@ -30,6 +30,21 @@ export class VorbisDecoder {
         this.offset += len;
         return value;
     }
+    /** Decode the shared structure, leaving packet framing and metadata policy to callers. */
+    parseCommentList(createCountError = message => new VorbisCommentError(message)) {
+        const vendor = this.readStringUtf8();
+        return { vendor, comments: this.parseUserCommentList(createCountError) };
+    }
+    *parseUserCommentList(createCountError) {
+        const count = this.readInt32();
+        // Each entry needs at least its four-byte length, even for an empty comment.
+        if (count > Math.floor(this.remaining / 4)) {
+            throw createCountError(`Vorbis comment count ${count} exceeds remaining data`);
+        }
+        for (let i = 0; i < count; ++i) {
+            yield this.parseUserComment();
+        }
+    }
     parseUserComment() {
         const offset0 = this.offset;
         const v = this.readStringUtf8();

package/lib/ogg/vorbis/VorbisStream.js

@@ -1,5 +1,4 @@
 import debugInit from 'debug';
-import * as Token from 'token-types';
 import { validateAllocation } from '../../common/Allocation.js';
 import { makeUnexpectedFileContentError } from '../../ParseError.js';
 import { CommonHeader, IdentificationHeader, VorbisPictureToken } from './Vorbis.js';
@@ -141,14 +140,9 @@ export class VorbisStream {
      * Ref: https://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-840005.2
      */
     async parseUserCommentList(pageData, offset) {
-        const strLen = Token.UINT32_LE.get(pageData, offset);
-        offset += 4;
-        // const vendorString = new Token.StringType(strLen, 'utf-8').get(pageData, offset);
-        offset += strLen;
-        let userCommentListLength = Token.UINT32_LE.get(pageData, offset);
-        offset += 4;
-        while (userCommentListLength-- > 0) {
-            offset += await this.parseUserComment(pageData, offset);
+        const { comments } = new VorbisDecoder(pageData, offset).parseCommentList();
+        for (const tag of comments) {
+            await this.addTag(tag.key, tag.value);
         }
         this.isMetadataComplete = true;
     }

package/lib/type.d.ts

@@ -388,7 +388,7 @@ export interface IRatio {
      */
     dB: number;
 }
-export type FormatId = 'container' | 'duration' | 'bitrate' | 'containerDuration' | 'overallBitrate' | 'sampleRate' | 'bitsPerSample' | 'codec' | 'tool' | 'codecProfile' | 'lossless' | 'numberOfChannels' | 'numberOfSamples' | 'audioMD5' | 'chapters' | 'modificationTime' | 'creationTime' | 'trackPeakLevel' | 'trackGain' | 'albumGain' | 'hasAudio' | 'hasVideo';
+export type FormatId = keyof IFormat;
 export interface IAudioTrack {
     /** Number of decoded audio samples, when known. */
     numberOfSamples?: number;
@@ -603,6 +603,7 @@ export interface IOptions {
     /**
      * Maximum bytes buffered for a single metadata payload, accumulated Ogg packet, or tokenizer stream lookahead.
      * Defaults to 64 MiB (67108864 bytes). Must be a positive safe integer.
+     * Also caps file-type read buffers during media format and cover art MIME-type detection.
      * This is not a limit on total process memory or the size of skipped audio/video data.
      */
     maxMemoryAllocation?: number;
@@ -625,7 +626,8 @@ export interface IOptions {
      */
     includeChapters?: boolean;
     /**
-     * Set observer for async callbacks to common or format.
+     * Called synchronously after common tag or format updates. Returned promises are not awaited.
+     * Unchanged primitive format values do not trigger a callback.
      */
     observer?: Observer;
     /**

package/lib/wav/WaveParser.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 riff from '../riff/RiffChunk.js';
 import { BroadcastAudioExtensionChunk } from './BwfChunk.js';
 import * as WaveChunk from './WaveChunk.js';
@@ -101,9 +100,7 @@ export class WaveParser extends BasicParser {
                 case 'id3 ': // The way Picard, FooBar currently stores, ID3 meta-data
                 case 'ID3 ': {
                     // The way Mp3Tags stores 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);
                     break;
                 }
                 case 'data': {

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.2",
   "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.6.0",
     "token-types": "^6.1.2",
     "uint8array-extras": "^1.6.0",
     "win-guid": "^0.2.1"
@@ -136,12 +136,12 @@
     "@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",
     "del-cli": "^8.0.1",
-    "mime": "^4.1.0",
+    "mime": "^4.1.1",
     "mocha": "^12.0.3",
     "nodemon": "^3.1.14",
     "remark-cli": "^12.0.1",