music-metadata 9.0.3 → 10.0.0

package/lib/common/GenericTagMapper.d.ts

@@ -3,7 +3,7 @@ import { ITag } from '../type.js';
 import { INativeMetadataCollector, IWarningCollector } from './MetadataCollector.js';
 export interface IGenericTagMapper {
     /**
-     * Which tagType it able to map to the generic mapping format
+     * Which tagType is able to map to the generic mapping format
      */
     tagTypes: generic.TagType[];
     /**

package/lib/common/MetadataCollector.js

@@ -167,6 +167,14 @@ export class MetadataCollector {
                 if (this.common[tag.id] && this.common[tag.id].indexOf(tag.value) !== -1)
                     return;
                 break;
+            case 'comment':
+                if (typeof tag.value === 'string') {
+                    tag.value = { text: tag.value };
+                }
+                if (tag.value.descriptor === 'iTunPGAP') {
+                    this.setGenericTag(tagType, { id: 'gapless', value: tag.value.text === '1' });
+                }
+                break;
             default:
             // nothing to do
         }

package/lib/core.d.ts

@@ -5,6 +5,7 @@ import * as strtok3 from 'strtok3';
 import type { IAudioMetadata, INativeTagDict, IOptions, IPicture, IPrivateOptions, IRandomReader, ITag } from './type.js';
 import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
 export { IFileInfo } from 'strtok3';
+export { IAudioMetadata, IOptions, ITag, INativeTagDict, ICommonTagsResult, IFormat, IPicture, IRatio, IChapter, ILyricsTag, LyricsContentType, TimestampFormat } from './type.js';
 export type AnyWebStream<G> = NodeReadableStream<G> | ReadableStream<G>;
 /**
  * Parse Web API File

package/lib/core.js

@@ -7,6 +7,7 @@ import { RandomUint8ArrayReader } from './common/RandomUint8ArrayReader.js';
 import { APEv2Parser } from './apev2/APEv2Parser.js';
 import { hasID3v1Header } from './id3v1/ID3v1Parser.js';
 import { getLyricsHeaderLength } from './lyrics3/Lyrics3.js';
+export { LyricsContentType, TimestampFormat } from './type.js';
 /**
  * Parse Web API File
  * Requires Blob to be able to stream using a ReadableStreamBYOBReader, only available since Node.js ≥ 20

package/lib/id3v2/FrameParser.d.ts

@@ -1,4 +1,4 @@
-import { ID3v2MajorVersion } from './ID3v2Token.js';
+import { ID3v2MajorVersion, ITextEncoding } from './ID3v2Token.js';
 import { IWarningCollector } from '../common/MetadataCollector.js';
 export declare function parseGenre(origVal: string): string[];
 export declare class FrameParser {
@@ -11,6 +11,10 @@ export declare class FrameParser {
      */
     constructor(major: ID3v2MajorVersion, warningCollector: IWarningCollector);
     readData(uint8Array: Uint8Array, type: string, includeCovers: boolean): any;
+    protected static readNullTerminatedString(uint8Array: Uint8Array, encoding: ITextEncoding): {
+        text: string;
+        len: number;
+    };
     protected static fixPictureMimeType(pictureType: string): string;
     /**
      * Converts TMCL (Musician credits list) or TIPL (Involved people list)

package/lib/id3v2/FrameParser.js

@@ -1,7 +1,7 @@
 import initDebug from 'debug';
 import * as Token from 'token-types';
 import * as util from '../common/Util.js';
-import { AttachedPictureType, TextEncodingToken } from './ID3v2Token.js';
+import { AttachedPictureType, TextEncodingToken, SyncTextHeader, TextHeader } from './ID3v2Token.js';
 import { Genres } from '../id3v1/ID3v1Parser.js';
 const debug = initDebug('music-metadata:id3v2:frame-parser');
 const defaultEnc = 'latin1'; // latin1 == iso-8859-1;
@@ -75,7 +75,6 @@ export class FrameParser {
         let output = []; // ToDo
         const nullTerminatorLength = FrameParser.getNullTerminatorLength(encoding);
         let fzero;
-        const out = {};
         debug(`Parsing tag type=${type}, encoding=${encoding}, bom=${bom}`);
         switch (type !== 'TXXX' && type[0] === 'T' ? 'T*' : type) {
             case 'T*': // 4.2.1. Text information frames - details
@@ -168,31 +167,49 @@ export class FrameParser {
                 output = Token.UINT32_BE.get(uint8Array, 0);
                 break;
             case 'SYLT':
-                // skip text encoding (1 byte),
-                //      language (3 bytes),
-                //      time stamp format (1 byte),
-                //      content tagTypes (1 byte),
-                //      content descriptor (1 byte)
-                offset += 7;
-                output = [];
+                const syltHeader = SyncTextHeader.get(uint8Array, 0);
+                offset += SyncTextHeader.len;
+                const result = {
+                    descriptor: '',
+                    language: syltHeader.language,
+                    contentType: syltHeader.contentType,
+                    timeStampFormat: syltHeader.timeStampFormat,
+                    syncText: []
+                };
+                let readSyllables = false;
                 while (offset < length) {
-                    const txt = uint8Array.slice(offset, offset = util.findZero(uint8Array, offset, length, encoding));
-                    offset += 5; // push offset forward one +  4 byte timestamp
-                    output.push(util.decodeString(txt, encoding));
+                    const nullStr = FrameParser.readNullTerminatedString(uint8Array.subarray(offset), syltHeader.encoding);
+                    offset += nullStr.len;
+                    if (readSyllables) {
+                        const timestamp = Token.UINT32_BE.get(uint8Array, offset);
+                        offset += Token.UINT32_BE.len;
+                        result.syncText.push({
+                            text: nullStr.text,
+                            timestamp
+                        });
+                    }
+                    else {
+                        result.descriptor = nullStr.text;
+                        readSyllables = true;
+                    }
                 }
+                output = result;
                 break;
             case 'ULT':
             case 'USLT':
             case 'COM':
             case 'COMM':
-                offset += 1;
-                out.language = util.decodeString(uint8Array.slice(offset, offset + 3), defaultEnc);
-                offset += 3;
-                fzero = util.findZero(uint8Array, offset, length, encoding);
-                out.description = util.decodeString(uint8Array.slice(offset, fzero), encoding);
-                offset = fzero + nullTerminatorLength;
-                out.text = util.decodeString(uint8Array.slice(offset, length), encoding).replace(/\x00+$/, '');
-                output = [out];
+                const textHeader = TextHeader.get(uint8Array, offset);
+                offset += TextHeader.len;
+                const descriptorStr = FrameParser.readNullTerminatedString(uint8Array.subarray(offset), textHeader.encoding);
+                offset += descriptorStr.len;
+                const textStr = FrameParser.readNullTerminatedString(uint8Array.subarray(offset), textHeader.encoding);
+                const comment = {
+                    language: textHeader.language,
+                    descriptor: descriptorStr.text,
+                    text: textStr.text
+                };
+                output = comment;
                 break;
             case 'UFID':
                 output = FrameParser.readIdentifierAndData(uint8Array, offset, length, defaultEnc);
@@ -265,6 +282,15 @@ export class FrameParser {
         }
         return output;
     }
+    static readNullTerminatedString(uint8Array, encoding) {
+        let offset = encoding.bom ? 2 : 0;
+        const txt = uint8Array.slice(offset, offset = util.findZero(uint8Array, offset, uint8Array.length, encoding.encoding));
+        offset += encoding.encoding === 'utf-16le' ? 2 : 1;
+        return {
+            text: util.decodeString(txt, encoding.encoding),
+            len: offset
+        };
+    }
     static fixPictureMimeType(pictureType) {
         pictureType = pictureType.toLocaleLowerCase();
         switch (pictureType) {

package/lib/id3v2/ID3v22TagMapper.js

@@ -27,12 +27,6 @@ export const id3v22TagMap = {
     TEN: 'encodedby',
     TSS: 'encodersettings',
     WAR: 'website',
-    'COM:iTunPGAP': 'gapless'
-    /* ToDo: iTunes tags:
-    'COM:iTunNORM': ,
-    'COM:iTunSMPB': 'encoder delay',
-    'COM:iTunes_CDDB_IDs'
-    */ ,
     PCS: 'podcast',
     TCP: "compilation",
     TDR: 'date',

package/lib/id3v2/ID3v24TagMapper.js

@@ -155,7 +155,6 @@ export class ID3v24TagMapper extends CaseInsensitiveTagMap {
      * @param warnings Wil be used to register (collect) warnings
      */
     postMap(tag, warnings) {
-        var _a, _b;
         switch (tag.id) {
             case 'UFID': // decode MusicBrainz Recording Id
                 if (tag.value.owner_identifier === 'http://musicbrainz.org') {
@@ -178,15 +177,9 @@ export class ID3v24TagMapper extends CaseInsensitiveTagMap {
                         warnings.addWarning(`Unknown PRIV owner-identifier: ${tag.value.owner_identifier}`);
                 }
                 break;
-            case 'COMM':
-                tag.value = (_a = tag.value) === null || _a === void 0 ? void 0 : _a.text;
-                break;
             case 'POPM':
                 tag.value = ID3v24TagMapper.toRating(tag.value);
                 break;
-            case 'USLT':
-                tag.value = (_b = tag.value) === null || _b === void 0 ? void 0 : _b.text;
-                break;
             default:
                 break;
         }

package/lib/id3v2/ID3v2Parser.d.ts

@@ -22,6 +22,7 @@ export declare class ID3v2Parser {
     parseExtendedHeader(): Promise<void>;
     parseExtendedHeaderData(dataRemaining: number, extendedHeaderSize: number): Promise<void>;
     parseId3Data(dataLen: number): Promise<void>;
+    private handleTag;
     private addTag;
     private parseMetadata;
     private readFrameHeader;

package/lib/id3v2/ID3v2Parser.js

@@ -97,25 +97,20 @@ export class ID3v2Parser {
     async parseId3Data(dataLen) {
         const uint8Array = await this.tokenizer.readToken(new Token.Uint8ArrayType(dataLen));
         for (const tag of this.parseMetadata(uint8Array)) {
-            if (tag.id === 'TXXX') {
-                if (tag.value) {
-                    await Promise.all(tag.value.text.map(text => this.addTag(ID3v2Parser.makeDescriptionTagName(tag.id, tag.value.description), text)));
-                }
-            }
-            else if (tag.id === 'COM') {
-                await Promise.all(tag.value.map(value => this.addTag(ID3v2Parser.makeDescriptionTagName(tag.id, value.description), value.text)));
-            }
-            else if (tag.id === 'COMM') {
-                await Promise.all(tag.value.map(value => this.addTag(ID3v2Parser.makeDescriptionTagName(tag.id, value.description), value)));
-            }
-            else if (Array.isArray(tag.value)) {
-                await Promise.all(tag.value.map(value => this.addTag(tag.id, value)));
-            }
-            else {
-                await this.addTag(tag.id, tag.value);
+            switch (tag.id) {
+                case 'TXXX':
+                    if (tag.value) {
+                        await this.handleTag(tag, tag.value.text, () => tag.value.description);
+                    }
+                    break;
+                default:
+                    await (Array.isArray(tag.value) ? Promise.all(tag.value.map(value => this.addTag(tag.id, value))) : this.addTag(tag.id, tag.value));
             }
         }
     }
+    async handleTag(tag, values, descriptor, resolveValue = value => value) {
+        await Promise.all(values.map(value => this.addTag(ID3v2Parser.makeDescriptionTagName(tag.id, descriptor(value)), resolveValue(value))));
+    }
     async addTag(id, value) {
         await this.metadata.addTag(this.headerType, id, value);
     }

package/lib/id3v2/ID3v2Token.d.ts

@@ -34,6 +34,23 @@ export interface IExtendedHeader {
     sizeOfPadding: number;
     crcDataPresent: boolean;
 }
+/**
+ * https://id3.org/id3v2.3.0#Synchronised_lyrics.2Ftext
+ */
+export declare enum LyricsContentType {
+    other = 0,
+    lyrics = 1,
+    text = 2,
+    movement_part = 3,
+    events = 4,
+    chord = 5,
+    trivia_pop = 6
+}
+export declare enum TimestampFormat {
+    notSynchronized0 = 0,
+    mpegFrameNumber = 1,
+    milliseconds = 2
+}
 /**
  * 28 bits (representing up to 256MB) integer, the msb is 0 to avoid 'false syncsignals'.
  * 4 * %0xxxxxxx
@@ -71,3 +88,25 @@ export interface ITextEncoding {
     bom?: boolean;
 }
 export declare const TextEncodingToken: IGetToken<ITextEncoding>;
+/**
+ * `USLT` frame fields
+ */
+export interface ITextHeader {
+    encoding: ITextEncoding;
+    language: string;
+}
+/**
+ * Used to read first portion of `SYLT` frame
+ */
+export declare const TextHeader: IGetToken<ITextHeader>;
+/**
+ * SYLT` frame fields
+ */
+export interface ISyncTextHeader extends ITextHeader {
+    contentType: LyricsContentType;
+    timeStampFormat: TimestampFormat;
+}
+/**
+ * Used to read first portion of `SYLT` frame
+ */
+export declare const SyncTextHeader: IGetToken<ISyncTextHeader>;

package/lib/id3v2/ID3v2Token.js

@@ -28,6 +28,25 @@ export var AttachedPictureType;
     AttachedPictureType[AttachedPictureType["Band/artist logotype"] = 19] = "Band/artist logotype";
     AttachedPictureType[AttachedPictureType["Publisher/Studio logotype"] = 20] = "Publisher/Studio logotype";
 })(AttachedPictureType || (AttachedPictureType = {}));
+/**
+ * https://id3.org/id3v2.3.0#Synchronised_lyrics.2Ftext
+ */
+export var LyricsContentType;
+(function (LyricsContentType) {
+    LyricsContentType[LyricsContentType["other"] = 0] = "other";
+    LyricsContentType[LyricsContentType["lyrics"] = 1] = "lyrics";
+    LyricsContentType[LyricsContentType["text"] = 2] = "text";
+    LyricsContentType[LyricsContentType["movement_part"] = 3] = "movement_part";
+    LyricsContentType[LyricsContentType["events"] = 4] = "events";
+    LyricsContentType[LyricsContentType["chord"] = 5] = "chord";
+    LyricsContentType[LyricsContentType["trivia_pop"] = 6] = "trivia_pop";
+})(LyricsContentType || (LyricsContentType = {}));
+export var TimestampFormat;
+(function (TimestampFormat) {
+    TimestampFormat[TimestampFormat["notSynchronized0"] = 0] = "notSynchronized0";
+    TimestampFormat[TimestampFormat["mpegFrameNumber"] = 1] = "mpegFrameNumber";
+    TimestampFormat[TimestampFormat["milliseconds"] = 2] = "milliseconds";
+})(TimestampFormat || (TimestampFormat = {}));
 /**
  * 28 bits (representing up to 256MB) integer, the msb is 0 to avoid 'false syncsignals'.
  * 4 * %0xxxxxxx
@@ -101,3 +120,31 @@ export const TextEncodingToken = {
         }
     }
 };
+/**
+ * Used to read first portion of `SYLT` frame
+ */
+export const TextHeader = {
+    len: 4,
+    get: (uint8Array, off) => {
+        return {
+            encoding: TextEncodingToken.get(uint8Array, off),
+            language: new Token.StringType(3, 'latin1').get(uint8Array, off + 1)
+        };
+    }
+};
+/**
+ * Used to read first portion of `SYLT` frame
+ */
+export const SyncTextHeader = {
+    len: 6,
+    get: (uint8Array, off) => {
+        const text = TextHeader.get(uint8Array, off);
+        return {
+            encoding: text.encoding,
+            language: text.language,
+            timeStampFormat: Token.UINT8.get(uint8Array, off + 4),
+            contentType: Token.UINT8.get(uint8Array, off + 5)
+        };
+    }
+};
+//# sourceMappingURL=ID3v2Token.js.map

package/lib/index.d.ts

@@ -4,7 +4,7 @@
 import * as Stream from 'stream';
 import * as strtok3 from 'strtok3';
 import { IAudioMetadata, IOptions } from './type.js';
-export { IAudioMetadata, IOptions, ITag, INativeTagDict, ICommonTagsResult, IFormat, IPicture, IRatio, IChapter } from './type.js';
+export { IAudioMetadata, IOptions, ITag, INativeTagDict, ICommonTagsResult, IFormat, IPicture, IRatio, IChapter, ILyricsTag, LyricsContentType, TimestampFormat } from './type.js';
 export { parseFromTokenizer, parseBuffer, parseBlob, parseWebStream, selectCover, orderTags, ratingToStars, IFileInfo } from './core.js';
 /**
  * Parse audio from Node Stream.Readable

package/lib/index.js

@@ -6,6 +6,7 @@ import initDebug from 'debug';
 import { parseFromTokenizer, scanAppendingHeaders } from './core.js';
 import { ParserFactory } from './ParserFactory.js';
 import { RandomFileReader } from './common/RandomFileReader.js';
+export { LyricsContentType, TimestampFormat } from './type.js';
 export { parseFromTokenizer, parseBuffer, parseBlob, parseWebStream, selectCover, orderTags, ratingToStars } from './core.js';
 const debug = initDebug('music-metadata:parser');
 /**

package/lib/type.d.ts

@@ -1,7 +1,9 @@
 import { GenericTagId, TagType } from './common/GenericTagTypes.js';
 import { IFooter } from './apev2/APEv2Token.js';
 import { TrackType } from './matroska/types.js';
+import { LyricsContentType, TimestampFormat } from './id3v2/ID3v2Token.js';
 export { TrackType } from './matroska/types.js';
+export { LyricsContentType, TimestampFormat } from './id3v2/ID3v2Token.js';
 /**
  * Attached picture, typically used for cover art
  */
@@ -92,7 +94,7 @@ export interface ICommonTagsResult {
     /**
      * List of comments
      */
-    comment?: string[];
+    comment?: IComment[];
     /**
      * Genre
      */
@@ -106,9 +108,9 @@ export interface ICommonTagsResult {
      */
     composer?: string[];
     /**
-     * Lyrics
+     * Synchronized lyrics
      */
-    lyrics?: string[];
+    lyrics?: ILyricsTag[];
     /**
      * Album title, formatted for alphabetic ordering
      */
@@ -593,3 +595,24 @@ export interface IRandomReader {
      */
     randomRead(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
 }
+interface ILyricsText {
+    text: string;
+    timestamp?: number;
+}
+export interface IComment {
+    descriptor?: string;
+    language?: string;
+    text?: string;
+}
+export interface ILyricsTag extends IComment {
+    contentType: LyricsContentType;
+    timeStampFormat: TimestampFormat;
+    /**
+     * Un-synchronized lyrics
+     */
+    text?: string;
+    /**
+     * Synchronized lyrics
+     */
+    syncText: ILyricsText[];
+}

package/lib/type.js

@@ -1,2 +1,3 @@
 export { TrackType } from './matroska/types.js';
+export { LyricsContentType, TimestampFormat } from './id3v2/ID3v2Token.js';
 //# sourceMappingURL=type.js.map

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": "9.0.3",
+  "version": "10.0.0",
   "author": {
     "name": "Borewit",
     "url": "https://github.com/Borewit"
@@ -84,7 +84,7 @@
     "compile-test": "tsc -p test",
     "compile-doc": "tsc -p doc-gen",
     "compile": "npm run compile-src && npm run compile-test && npm run compile-doc",
-    "eslint": "eslint lib/**/*.ts --ignore-pattern lib/**/*.d.ts example/typescript/**/*.ts test/**/*.ts doc-gen/**/*.ts",
+    "eslint": "eslint lib test doc-gen",
     "lint-md": "remark -u preset-lint-markdown-style-guide .",
     "lint": "npm run lint-md && npm run eslint",
     "test": "mocha",
@@ -105,25 +105,29 @@
     "uint8array-extras": "^1.4.0"
   },
   "devDependencies": {
+    "@eslint/compat": "^1.1.1",
+    "@eslint/eslintrc": "^3.1.0",
+    "@eslint/js": "^9.7.0",
     "@types/chai": "^4.3.16",
     "@types/chai-as-promised": "^7.1.8",
     "@types/debug": "^4.1.12",
     "@types/file-type": "^10.9.1",
     "@types/mocha": "^10.0.7",
     "@types/node": "^20.14.11",
-    "@typescript-eslint/eslint-plugin": "^7.16.0",
-    "@typescript-eslint/parser": "^7.16.0",
+    "@typescript-eslint/eslint-plugin": "^7.16.1",
+    "@typescript-eslint/parser": "^7.16.1",
     "c8": "^10.1.2",
     "chai": "^5.1.1",
     "chai-as-promised": "^8.0.0",
     "del-cli": "^5.1.0",
-    "eslint": "^8.57.0",
+    "eslint": "^9.7.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-jsdoc": "^48.7.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-unicorn": "^54.0.0",
+    "globals": "^15.8.0",
     "mime": "^4.0.4",
     "mocha": "^10.6.0",
     "npm-run-all": "^4.1.5",