music-metadata 11.10.6 → 11.11.0

package/README.md

@@ -1,12 +1,11 @@
 [![CI](https://github.com/Borewit/music-metadata/actions/workflows/ci.yml/badge.svg)](https://github.com/Borewit/music-metadata/actions/workflows/ci.yml)
 [![NPM version](https://img.shields.io/npm/v/music-metadata.svg)](https://npmjs.org/package/music-metadata)
-[![npm downloads](http://img.shields.io/npm/dm/music-metadata.svg)](https://npmcharts.com/compare/music-metadata?start=600&interval=30)
+[![npm downloads](http://img.shields.io/npm/dm/music-metadata.svg)](https://npmcharts.com/compare/music-metadata?start=600&interval=7)
 [![Coverage Status](https://coveralls.io/repos/github/Borewit/music-metadata/badge.svg?branch=master)](https://coveralls.io/github/Borewit/music-metadata?branch=master)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/57d731b05c9e41889a2a17cb4b0384d7)](https://app.codacy.com/app/Borewit/music-metadata?utm_source=github.com&utm_medium=referral&utm_content=Borewit/music-metadata&utm_campaign=Badge_Grade_Dashboard)
 [![CodeQL](https://github.com/Borewit/music-metadata/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Borewit/music-metadata/actions/workflows/codeql-analysis.yml)
 [![DeepScan grade](https://deepscan.io/api/teams/5165/projects/6938/branches/61821/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=5165&pid=6938&bid=61821)
 [![Known Vulnerabilities](https://snyk.io/test/github/Borewit/music-metadata/badge.svg?targetFile=package.json)](https://snyk.io/test/github/Borewit/music-metadata?targetFile=package.json)
-[![Discord](https://img.shields.io/discord/460524735235883049.svg)](https://discord.gg/KyBr6sb)
 
 # music-metadata
 
@@ -74,7 +73,7 @@ Following tag header formats are supported:
 - [APE](https://wikipedia.org/wiki/APE_tag)
 - [ASF](https://wikipedia.org/wiki/Advanced_Systems_Format)
 - EXIF 2.3
-- [ID3](https://wikipedia.org/wiki/ID3): ID3v1, ID3v1.1, ID3v2.2, [ID3v2.3](http://id3.org/id3v2.3.0) & [ID3v2.4](http://id3.org/id3v2.4.0-frames)
+- [ID3](https://wikipedia.org/wiki/ID3): ID3v1, ID3v1.1, ID3v2.2, [ID3v2.3](http://id3.org/id3v2.3.0), [ID3v2.4](http://id3.org/id3v2.4.0-frames) and [ID3v2 Chapters 1.0](https://mutagen-specs.readthedocs.io/en/latest/id3/id3v2-chapters-1.0.html)
 - [iTunes](https://github.com/sergiomb2/libmp4v2/wiki/iTunesMetadata)
 - [RIFF](https://wikipedia.org/wiki/Resource_Interchange_File_Format)/INFO
 - [Vorbis comment](https://wikipedia.org/wiki/Vorbis_comment)

package/lib/id3v2/FrameParser.d.ts

@@ -1,5 +1,6 @@
 import { type ID3v2MajorVersion, type ITextEncoding } from './ID3v2Token.js';
 import type { IWarningCollector } from '../common/MetadataCollector.js';
+import { type IChapterInfo } from './ID3v2ChapterToken.js';
 interface ICustomTag {
     owner_identifier: string;
 }
@@ -24,6 +25,22 @@ export interface IGeneralEncapsulatedObject {
     description: string;
     data: Uint8Array;
 }
+export type Chapter = {
+    label: string;
+    info: IChapterInfo;
+    frames: Map<string, unknown>;
+};
+export type TableOfContents = {
+    label: string;
+    flags: {
+        /** If set, this is the top-level table of contents */
+        topLevel: boolean;
+        /** If set, the child element IDs are in a defined order */
+        ordered: boolean;
+    };
+    childElementIds: string[];
+    frames: Map<string, unknown>;
+};
 export declare function parseGenre(origVal: string): string[];
 export declare class FrameParser {
     private major;

package/lib/id3v2/FrameParser.js

@@ -5,6 +5,8 @@ import { AttachedPictureType, SyncTextHeader, TextEncodingToken, TextHeader } fr
 import { Genres } from '../id3v1/ID3v1Parser.js';
 import { makeUnexpectedFileContentError } from '../ParseError.js';
 import { decodeUintBE } from '../common/Util.js';
+import { ChapterInfo } from './ID3v2ChapterToken.js';
+import { getFrameHeaderLength, readFrameHeader } from './FrameHeader.js';
 const debug = initDebug('music-metadata:id3v2:frame-parser');
 const defaultEnc = 'latin1'; // latin1 == iso-8859-1;
 const urlEnc = { encoding: defaultEnc, bom: false };
@@ -109,6 +111,9 @@ export class FrameParser {
                     case 'TRK':
                     case 'TRCK':
                     case 'TPOS':
+                    case 'TIT1':
+                    case 'TIT2':
+                    case 'TIT3':
                         output = text;
                         break;
                     case 'TCOM':
@@ -137,11 +142,10 @@ export class FrameParser {
             }
             case 'TXXX': {
                 const idAndData = FrameParser.readIdentifierAndData(uint8Array.subarray(1), encoding);
-                const textTag = {
+                output = {
                     description: idAndData.id,
                     text: this.splitValue(type, util.decodeString(idAndData.data, encoding).replace(/\x00+$/, ''))
                 };
-                output = textTag;
                 break;
             }
             case 'PIC':
@@ -310,6 +314,67 @@ export class FrameParser {
                 output = uint8Array.subarray(0, length);
                 break;
             }
+            // ID3v2 Chapters 1.0
+            // https://mutagen-specs.readthedocs.io/en/latest/id3/id3v2-chapters-1.0.html#chapter-frame
+            case 'CHAP': { //  // Chapter frame
+                debug("Reading CHAP");
+                fzero = util.findZero(uint8Array, defaultEnc);
+                const chapter = {
+                    label: util.decodeString(uint8Array.subarray(0, fzero), defaultEnc),
+                    info: ChapterInfo.get(uint8Array, fzero + 1),
+                    frames: new Map()
+                };
+                offset += fzero + 1 + ChapterInfo.len;
+                while (offset < length) {
+                    const subFrame = readFrameHeader(uint8Array.subarray(offset), this.major, this.warningCollector);
+                    const headerSize = getFrameHeaderLength(this.major);
+                    offset += headerSize;
+                    const subOutput = this.readData(uint8Array.subarray(offset, offset + subFrame.length), subFrame.id, includeCovers);
+                    offset += subFrame.length;
+                    chapter.frames.set(subFrame.id, subOutput);
+                }
+                output = chapter;
+                break;
+            }
+            // ID3v2 Chapters 1.0
+            // https://mutagen-specs.readthedocs.io/en/latest/id3/id3v2-chapters-1.0.html#table-of-contents-frame
+            case 'CTOC': { // Table of contents frame
+                debug('Reading CTOC');
+                // Element ID (null-terminated latin1)
+                const idEnd = util.findZero(uint8Array, defaultEnc);
+                const label = util.decodeString(uint8Array.subarray(0, idEnd), defaultEnc);
+                offset = idEnd + 1;
+                // Flags
+                const flags = uint8Array[offset++];
+                const topLevel = (flags & 0x02) !== 0;
+                const ordered = (flags & 0x01) !== 0;
+                // Child element IDs
+                const entryCount = uint8Array[offset++];
+                const childElementIds = [];
+                for (let i = 0; i < entryCount && offset < length; i++) {
+                    const end = util.findZero(uint8Array.subarray(offset), defaultEnc);
+                    const childId = util.decodeString(uint8Array.subarray(offset, offset + end), defaultEnc);
+                    childElementIds.push(childId);
+                    offset += end + 1;
+                }
+                const toc = {
+                    label,
+                    flags: { topLevel, ordered },
+                    childElementIds,
+                    frames: new Map()
+                };
+                // Optional embedded sub-frames (e.g. TIT2) follow after the child list
+                while (offset < length) {
+                    const subFrame = readFrameHeader(uint8Array.subarray(offset), this.major, this.warningCollector);
+                    const headerSize = getFrameHeaderLength(this.major);
+                    offset += headerSize;
+                    const subOutput = this.readData(uint8Array.subarray(offset, offset + subFrame.length), subFrame.id, includeCovers);
+                    offset += subFrame.length;
+                    toc.frames.set(subFrame.id, subOutput);
+                }
+                output = toc;
+                break;
+            }
             default:
                 debug(`Warning: unsupported id3v2-tag-type: ${type}`);
                 break;

package/lib/id3v2/ID3v2ChapterToken.d.ts

@@ -0,0 +1,11 @@
+import type { IGetToken } from 'strtok3';
+export interface IChapterInfo {
+    startTime: number;
+    endTime: number;
+    startOffset?: number;
+    endOffset?: number;
+}
+/**
+ * Data portion of `CHAP` sub frame
+ */
+export declare const ChapterInfo: IGetToken<IChapterInfo>;

package/lib/id3v2/ID3v2ChapterToken.js

@@ -0,0 +1,17 @@
+import * as Token from 'token-types';
+/**
+ * Data portion of `CHAP` sub frame
+ */
+export const ChapterInfo = {
+    len: 16,
+    get: (buf, off) => {
+        const startOffset = Token.UINT32_BE.get(buf, off + 8);
+        const endOffset = Token.UINT32_BE.get(buf, off + 12);
+        return {
+            startTime: Token.UINT32_BE.get(buf, off),
+            endTime: Token.UINT32_BE.get(buf, off + 4),
+            startOffset: startOffset === 0xFFFFFFFF ? undefined : startOffset,
+            endOffset: endOffset === 0xFFFFFFFF ? undefined : endOffset,
+        };
+    }
+};

package/lib/id3v2/ID3v2Parser.d.ts

@@ -23,4 +23,11 @@ export declare class ID3v2Parser {
     private handleTag;
     private addTag;
     private parseMetadata;
+    /**
+     * Convert parsed ID3v2 chapter frames (CHAP / CTOC) to generic `format.chapters`.
+     *
+     * This function expects the `native` tags already to contain parsed `CHAP` and `CTOC` frame values,
+     * as produced by `FrameParser.readData`.
+     */
+    private static mapId3v2Chapters;
 }

package/lib/id3v2/ID3v2Parser.js

@@ -62,7 +62,10 @@ export class ID3v2Parser {
         }
         this.id3Header = id3Header;
         this.headerType = (`ID3v2.${id3Header.version.major}`);
-        return id3Header.flags.isExtendedHeader ? this.parseExtendedHeader() : this.parseId3Data(id3Header.size);
+        await (id3Header.flags.isExtendedHeader ? this.parseExtendedHeader() : this.parseId3Data(id3Header.size));
+        // Post process
+        const chapters = ID3v2Parser.mapId3v2Chapters(this.metadata.native[this.headerType], this.metadata.format.sampleRate);
+        this.metadata.setFormat('chapters', chapters);
     }
     async parseExtendedHeader() {
         const extendedHeader = await this.tokenizer.readToken(ExtendedHeader);
@@ -116,6 +119,48 @@ export class ID3v2Parser {
         }
         return tags;
     }
+    /**
+     * Convert parsed ID3v2 chapter frames (CHAP / CTOC) to generic `format.chapters`.
+     *
+     * This function expects the `native` tags already to contain parsed `CHAP` and `CTOC` frame values,
+     * as produced by `FrameParser.readData`.
+     */
+    static mapId3v2Chapters(id3Tags, sampleRate) {
+        const chapFrames = id3Tags.filter(t => t.id === 'CHAP');
+        if (!chapFrames?.length)
+            return;
+        const tocFrames = id3Tags.filter(t => t.id === 'CTOC');
+        const topLevelToc = tocFrames?.find(t => t.value.flags?.topLevel);
+        const chapterById = new Map();
+        for (const chap of chapFrames) {
+            chapterById.set(chap.value.label, chap.value);
+        }
+        const orderedIds = topLevelToc?.value.childElementIds;
+        const chapters = [];
+        const source = orderedIds ?? [...chapterById.keys()];
+        for (const id of source) {
+            const chap = chapterById.get(id);
+            if (!chap)
+                continue;
+            const frames = chap.frames;
+            const title = frames.get('TIT2');
+            if (!title)
+                continue; // title is required
+            chapters.push({
+                id,
+                title,
+                url: frames.get('WXXX'),
+                start: chap.info.startTime / 1000,
+                end: chap.info.endTime / 1000,
+                image: frames.get('APIC')
+            });
+        }
+        // If no ordered CTOC, sort by time
+        if (!orderedIds) {
+            chapters.sort((a, b) => a.start - b.start);
+        }
+        return chapters.length ? chapters : undefined;
+    }
 }
 function makeUnexpectedMajorVersionError(majorVer) {
     throw new Id3v2ContentError(`Unexpected majorVer: ${majorVer}`);

package/lib/id3v2/ID3v2Token.d.ts

@@ -57,10 +57,7 @@ export type TimestampFormat = typeof TimestampFormat[keyof typeof TimestampForma
  * 28 bits (representing up to 256MB) integer, the msb is 0 to avoid 'false syncsignals'.
  * 4 * %0xxxxxxx
  */
-export declare const UINT32SYNCSAFE: {
-    get: (buf: Uint8Array, off: number) => number;
-    len: number;
-};
+export declare const UINT32SYNCSAFE: IGetToken<number>;
 /**
  * ID3v2 tag header
  */

package/lib/type.d.ts

@@ -484,25 +484,46 @@ export interface ITag {
     id: string;
     value: AnyTagValue;
 }
+export interface IUrl {
+    url: string;
+    description: string;
+}
 export interface IChapter {
+    /**
+     * Internal chapter reference
+     */
+    id?: string;
     /**
      * Chapter title
      */
     title: string;
+    /**
+     * URL
+     */
+    url?: IUrl;
     /**
      * Audio offset in sample number, 0 is the first sample.
      * Duration offset is sampleOffset / format.sampleRate
      */
-    sampleOffset: number;
+    sampleOffset?: number;
     /**
      * Timestamp where the chapter starts
      * Chapter timestamp is start/timeScale in seconds.
      */
     start: number;
     /**
-     * Time value that indicates the time scale for chapter tracks, the number of time units that pass per second in its time coordinate system.
+     * Timestamp where the chapter end
+     * Chapter timestamp is start/timeScale in seconds.
+     */
+    end?: number;
+    /**
+     * Time value that indicates the timescale for chapter tracks, the number of time units that pass per second in its time coordinate system.
+     */
+    timeScale?: number;
+    /**
+     * Picture
      */
-    timeScale: number;
+    image?: IPicture;
 }
 /**
  * Flat list of tags

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": "11.10.6",
+  "version": "11.11.0",
   "author": {
     "name": "Borewit",
     "url": "https://github.com/Borewit"
@@ -85,7 +85,9 @@
     "parser",
     "bwf",
     "slt",
-    "lyrics"
+    "lyrics",
+    "Chapters",
+    "ID3v2 Chapters"
   ],
   "scripts": {
     "clean": "del-cli 'lib/**/*.js' 'lib/**/*.js.map' 'lib/**/*.d.ts' 'test/**/*.js' 'test/**/*.js.map' 'test/**/*.js' 'test/**/*.js.map' 'doc-gen/**/*.js' 'doc-gen/**/*.js.map'",
@@ -115,7 +117,7 @@
     "strtok3": "^10.3.4",
     "token-types": "^6.1.2",
     "uint8array-extras": "^1.5.0",
-    "win-guid": "^0.1.3"
+    "win-guid": "^0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
@@ -125,7 +127,7 @@
     "@types/debug": "^4.1.12",
     "@types/media-typer": "^1.1.3",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.0.10",
     "c8": "^10.1.3",
     "chai": "^6.2.2",
     "chai-as-promised": "^8.0.2",