metadata-connect 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# metadata-connect
+
+Extract audio metadata from MP3, M4A, FLAC, and AIFF files with support for partial file reads - perfect for extracting metadata from remote files over the network without downloading entire files.
+
+[![npm version](https://badge.fury.io/js/metadata-connect.svg)](https://www.npmjs.com/package/metadata-connect)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Partial file reading** - Extract metadata by reading only file headers (10-200KB instead of entire files)
+- **Multiple format support** - MP3 (ID3v2), M4A/MP4/AAC, FLAC, AIFF
+- **Complete metadata extraction** - Title, artist, album, genre, year, BPM, key, and artwork
+- **FileReader abstraction** - Works with any data source (local files, NFS, HTTP range requests, custom protocols)
+- **Zero runtime dependencies** - Pure TypeScript implementation
+- **TypeScript first** - Full type definitions included
+
+## Installation
+
+```bash
+npm install metadata-connect
+```
+
+## Quick Start
+
+### Extract from a local file
+
+```typescript
+import { extractMetadata, createBufferReader } from 'metadata-connect';
+import { readFile } from 'fs/promises';
+
+const buffer = await readFile('song.mp3');
+const reader = createBufferReader(buffer, 'mp3');
+const metadata = await extractMetadata(reader);
+
+if (metadata) {
+  console.log(metadata.title);   // "Song Title"
+  console.log(metadata.artist);  // "Artist Name"
+  console.log(metadata.bpm);     // 128
+  console.log(metadata.key);     // "Am"
+
+  if (metadata.artwork) {
+    // metadata.artwork is a Buffer
+    // metadata.artworkMimeType is 'image/jpeg' | 'image/png' | 'image/gif'
+  }
+}
+```
+
+### Extract from a remote file (partial read)
+
+The real power of metadata-connect is extracting metadata from remote files without downloading them entirely:
+
+```typescript
+import { extractMetadata } from 'metadata-connect';
+import type { FileReader } from 'metadata-connect';
+
+// Create a FileReader that fetches only the requested bytes
+const reader: FileReader = {
+  size: fileSize, // Total file size (get from HEAD request or file stat)
+  extension: 'mp3',
+  async read(offset: number, length: number): Promise<Buffer> {
+    // Use HTTP Range requests, NFS, or any protocol
+    const response = await fetch(url, {
+      headers: { Range: `bytes=${offset}-${offset + length - 1}` }
+    });
+    return Buffer.from(await response.arrayBuffer());
+  }
+};
+
+const metadata = await extractMetadata(reader);
+```
+
+## API Reference
+
+### `extractMetadata(reader: FileReader): Promise<ExtractedMetadata | null>`
+
+Main extraction function. Returns metadata or null if the format is not supported or parsing fails.
+
+### `createBufferReader(buffer: Buffer, extension: string): FileReader`
+
+Create a FileReader from a Buffer for in-memory extraction.
+
+### `isExtensionSupported(extension: string): boolean`
+
+Check if a file extension is supported.
+
+### `getSupportedExtensions(): string[]`
+
+Get list of supported extensions: `['mp3', 'm4a', 'mp4', 'aac', 'flac', 'aiff', 'aif']`
+
+### `getParserForExtension(extension: string): MetadataParser | null`
+
+Get the parser function for a specific extension.
+
+## Types
+
+### `FileReader`
+
+```typescript
+interface FileReader {
+  /** Total file size in bytes */
+  readonly size: number;
+  /** File extension (without dot), e.g., 'mp3', 'flac' */
+  readonly extension: string;
+  /** Read bytes from the file at a given offset */
+  read(offset: number, length: number): Promise<Buffer>;
+}
+```
+
+### `ExtractedMetadata`
+
+```typescript
+interface ExtractedMetadata {
+  title?: string;
+  artist?: string;
+  album?: string;
+  genre?: string;
+  year?: number;
+  bpm?: number;
+  key?: string;
+  artwork?: Buffer;
+  artworkMimeType?: 'image/jpeg' | 'image/png' | 'image/gif';
+}
+```
+
+## Format Support
+
+| Format | Extension | Metadata Source |
+|--------|-----------|-----------------|
+| MP3 | `.mp3` | ID3v2.2, ID3v2.3, ID3v2.4 tags |
+| M4A/MP4 | `.m4a`, `.mp4`, `.aac` | iTunes metadata atoms |
+| FLAC | `.flac` | Vorbis comments + PICTURE blocks |
+| AIFF | `.aiff`, `.aif` | ID3 chunk |
+
+### Extracted Fields
+
+| Field | MP3 | M4A | FLAC | AIFF |
+|-------|-----|-----|------|------|
+| Title | TIT2 | ©nam | TITLE | ID3 |
+| Artist | TPE1 | ©ART | ARTIST | ID3 |
+| Album | TALB | ©alb | ALBUM | ID3 |
+| Genre | TCON | ©gen/gnre | GENRE | ID3 |
+| Year | TYER/TDRC | ©day | DATE | ID3 |
+| BPM | TBPM | tmpo | BPM/TEMPO | ID3 |
+| Key | TKEY | - | KEY/INITIALKEY | ID3 |
+| Artwork | APIC | covr | PICTURE | ID3 |
+
+## Network Efficiency
+
+The library is designed to minimize network transfer when reading from remote sources:
+
+| Format | Typical Bytes Read |
+|--------|-------------------|
+| MP3 | 10-50 KB (ID3v2 tag at file start) |
+| FLAC | 10 KB (metadata blocks at file start) |
+| M4A/MP4 | 50-200 KB (atom tree traversal) |
+| AIFF | 10-50 KB (ID3 chunk location varies) |
+
+## Use Cases
+
+- **DJ Software** - Extract track info from CDJs/controllers over network protocols
+- **Media Servers** - Index large music libraries without reading entire files
+- **Streaming Services** - Quick metadata lookup for remote storage
+- **Browser Applications** - Extract metadata using fetch with Range headers
+
+## Advanced Usage
+
+### Using Individual Parsers
+
+```typescript
+import { extractFromMp3, extractFromMp4, extractFromFlac } from 'metadata-connect';
+
+// Use specific parser directly
+const metadata = await extractFromMp3(reader);
+```
+
+### Detecting Image Types
+
+```typescript
+import { detectImageType } from 'metadata-connect';
+
+const mimeType = detectImageType(imageBuffer);
+// Returns 'image/jpeg' | 'image/png' | 'image/gif' | null
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [music-metadata](https://github.com/borewit/music-metadata) - Full-featured audio metadata library (requires full file access)
+- [node-id3](https://github.com/Zazama/node-id3) - ID3 tag reader/writer for Node.js

package/dist/extract.d.ts

@@ -0,0 +1,36 @@
+import type { ExtractedMetadata, FileReader, MetadataParser } from './types.js';
+/**
+ * Get the appropriate parser for a file extension
+ */
+export declare function getParserForExtension(extension: string): MetadataParser | null;
+/**
+ * Get list of supported file extensions
+ */
+export declare function getSupportedExtensions(): string[];
+/**
+ * Check if a file extension is supported
+ */
+export declare function isExtensionSupported(extension: string): boolean;
+/**
+ * Extract metadata from an audio file using the appropriate parser
+ *
+ * @param reader - FileReader interface for reading file data
+ * @returns Extracted metadata, or null if extraction fails or format is unsupported
+ *
+ * @example
+ * ```typescript
+ * // Create a reader from your transport layer
+ * const reader = createFileReader(device, path, fileSize);
+ *
+ * // Extract metadata
+ * const metadata = await extractMetadata(reader);
+ * if (metadata) {
+ *   console.log(metadata.title, metadata.artist);
+ *   if (metadata.artwork) {
+ *     // Use artwork buffer
+ *   }
+ * }
+ * ```
+ */
+export declare function extractMetadata(reader: FileReader): Promise<ExtractedMetadata | null>;
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6BhF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAG9E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAa3F"}

package/dist/extract.js

@@ -0,0 +1,77 @@
+import { extractFromMp3 } from './parsers/id3.js';
+import { extractFromMp4 } from './parsers/mp4.js';
+import { extractFromFlac } from './parsers/flac.js';
+import { extractFromAiff } from './parsers/aiff.js';
+/**
+ * Map of file extensions to their metadata parsers
+ */
+const PARSER_MAP = {
+    // MP3
+    mp3: extractFromMp3,
+    // MP4/M4A/AAC
+    m4a: extractFromMp4,
+    mp4: extractFromMp4,
+    m4p: extractFromMp4,
+    m4b: extractFromMp4,
+    aac: extractFromMp4,
+    // FLAC
+    flac: extractFromFlac,
+    // AIFF
+    aiff: extractFromAiff,
+    aif: extractFromAiff,
+    aifc: extractFromAiff,
+};
+/**
+ * Get the appropriate parser for a file extension
+ */
+export function getParserForExtension(extension) {
+    const normalizedExt = extension.toLowerCase().replace(/^\./, '');
+    return PARSER_MAP[normalizedExt] ?? null;
+}
+/**
+ * Get list of supported file extensions
+ */
+export function getSupportedExtensions() {
+    return Object.keys(PARSER_MAP);
+}
+/**
+ * Check if a file extension is supported
+ */
+export function isExtensionSupported(extension) {
+    return getParserForExtension(extension) !== null;
+}
+/**
+ * Extract metadata from an audio file using the appropriate parser
+ *
+ * @param reader - FileReader interface for reading file data
+ * @returns Extracted metadata, or null if extraction fails or format is unsupported
+ *
+ * @example
+ * ```typescript
+ * // Create a reader from your transport layer
+ * const reader = createFileReader(device, path, fileSize);
+ *
+ * // Extract metadata
+ * const metadata = await extractMetadata(reader);
+ * if (metadata) {
+ *   console.log(metadata.title, metadata.artist);
+ *   if (metadata.artwork) {
+ *     // Use artwork buffer
+ *   }
+ * }
+ * ```
+ */
+export async function extractMetadata(reader) {
+    const parser = getParserForExtension(reader.extension);
+    if (!parser) {
+        return null;
+    }
+    try {
+        return await parser(reader);
+    }
+    catch {
+        // Return null on any parsing error
+        return null;
+    }
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,GAAmC;IACjD,MAAM;IACN,GAAG,EAAE,cAAc;IAEnB,cAAc;IACd,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;IAEnB,OAAO;IACP,IAAI,EAAE,eAAe;IAErB,OAAO;IACP,IAAI,EAAE,eAAe;IACrB,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,eAAe;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,MAAM,aAAa,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjE,OAAO,UAAU,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAkB;IACtD,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAEvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { extractMetadata, getParserForExtension, getSupportedExtensions, isExtensionSupported, } from './extract.js';
+export type { FileReader, ExtractedMetadata, ArtworkMimeType, MetadataParser, } from './types.js';
+export { PictureType } from './types.js';
+export { createBufferReader } from './reader.js';
+export { extractFromMp3, extractFromMp4, extractFromFlac, extractFromAiff, detectImageType, normalizeMimeType, } from './parsers/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Main extraction function
+export { extractMetadata, getParserForExtension, getSupportedExtensions, isExtensionSupported, } from './extract.js';
+export { PictureType } from './types.js';
+// Reader utilities
+export { createBufferReader } from './reader.js';
+// Individual parsers (for advanced use cases)
+export { extractFromMp3, extractFromMp4, extractFromFlac, extractFromAiff, detectImageType, normalizeMimeType, } from './parsers/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,8CAA8C;AAC9C,OAAO,EACL,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/parsers/aiff.d.ts

@@ -0,0 +1,9 @@
+import type { ExtractedMetadata, FileReader } from '../types.js';
+/**
+ * Extract metadata from an AIFF file
+ *
+ * AIFF files can contain ID3v2 tags in an 'ID3 ' chunk.
+ * We look for this chunk and delegate to the ID3 parser.
+ */
+export declare function extractFromAiff(reader: FileReader): Promise<ExtractedMetadata | null>;
+//# sourceMappingURL=aiff.d.ts.map

package/dist/parsers/aiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aiff.d.ts","sourceRoot":"","sources":["../../src/parsers/aiff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIjE;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAuC3F"}

package/dist/parsers/aiff.js

@@ -0,0 +1,42 @@
+import { extractFromMp3 } from './id3.js';
+import { createBufferReader } from '../reader.js';
+/**
+ * Extract metadata from an AIFF file
+ *
+ * AIFF files can contain ID3v2 tags in an 'ID3 ' chunk.
+ * We look for this chunk and delegate to the ID3 parser.
+ */
+export async function extractFromAiff(reader) {
+    // Read AIFF header (12 bytes minimum)
+    const header = await reader.read(0, 12);
+    if (header.length < 12 || header.toString('ascii', 0, 4) !== 'FORM') {
+        return null;
+    }
+    const formType = header.toString('ascii', 8, 12);
+    if (formType !== 'AIFF' && formType !== 'AIFC') {
+        return null;
+    }
+    const formSize = header.readUInt32BE(4);
+    const fileEnd = Math.min(8 + formSize, reader.size);
+    let offset = 12;
+    // Iterate through chunks looking for ID3 tag
+    while (offset + 8 < fileEnd) {
+        const chunkHeader = await reader.read(offset, 8);
+        if (chunkHeader.length < 8)
+            break;
+        const chunkId = chunkHeader.toString('ascii', 0, 4);
+        const chunkSize = chunkHeader.readUInt32BE(4);
+        if (chunkSize <= 0 || offset + 8 + chunkSize > fileEnd)
+            break;
+        // Check for ID3 chunk (can be 'ID3 ' or 'id3 ')
+        if (chunkId === 'ID3 ' || chunkId === 'id3 ') {
+            const id3Data = await reader.read(offset + 8, chunkSize);
+            const id3Reader = createBufferReader(id3Data, 'mp3');
+            return extractFromMp3(id3Reader);
+        }
+        // AIFF chunks are padded to even byte boundaries
+        offset += 8 + chunkSize + (chunkSize % 2);
+    }
+    return null;
+}
+//# sourceMappingURL=aiff.js.map

package/dist/parsers/aiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aiff.js","sourceRoot":"","sources":["../../src/parsers/aiff.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAkB;IACtD,sCAAsC;IACtC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACjD,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAEpD,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,6CAA6C;IAC7C,OAAO,MAAM,GAAG,CAAC,GAAG,OAAO,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACjD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM;QAElC,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAE9C,IAAI,SAAS,IAAI,CAAC,IAAI,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO;YAAE,MAAM;QAE9D,gDAAgD;QAChD,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAC7C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACrD,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;QAED,iDAAiD;QACjD,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/parsers/flac.d.ts

@@ -0,0 +1,6 @@
+import type { ExtractedMetadata, FileReader } from '../types.js';
+/**
+ * Extract metadata from a FLAC file
+ */
+export declare function extractFromFlac(reader: FileReader): Promise<ExtractedMetadata | null>;
+//# sourceMappingURL=flac.d.ts.map

package/dist/parsers/flac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flac.d.ts","sourceRoot":"","sources":["../../src/parsers/flac.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAkJlF;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA4E3F"}

package/dist/parsers/flac.js

@@ -0,0 +1,172 @@
+import { PictureType } from '../types.js';
+import { normalizeMimeType, parseBpm, parseYear, cleanText } from './utils.js';
+/**
+ * Vorbis comment field names (case-insensitive)
+ */
+const VORBIS_FIELDS = {
+    TITLE: ['TITLE'],
+    ARTIST: ['ARTIST'],
+    ALBUM: ['ALBUM'],
+    GENRE: ['GENRE'],
+    DATE: ['DATE', 'YEAR'],
+    BPM: ['BPM', 'TEMPO'],
+    KEY: ['KEY', 'INITIALKEY'],
+};
+/**
+ * Parse a FLAC PICTURE metadata block
+ */
+function parsePictureBlock(data) {
+    if (data.length < 32)
+        return null;
+    let offset = 0;
+    const pictureType = data.readUInt32BE(offset);
+    offset += 4;
+    const mimeLength = data.readUInt32BE(offset);
+    offset += 4;
+    if (offset + mimeLength > data.length)
+        return null;
+    const mimeType = data.toString('utf8', offset, offset + mimeLength);
+    offset += mimeLength;
+    const descLength = data.readUInt32BE(offset);
+    offset += 4 + descLength;
+    if (offset + 16 > data.length)
+        return null;
+    const width = data.readUInt32BE(offset);
+    offset += 4;
+    const height = data.readUInt32BE(offset);
+    offset += 4 + 8; // Skip depth and colors
+    const imageLength = data.readUInt32BE(offset);
+    offset += 4;
+    if (offset + imageLength > data.length)
+        return null;
+    const imageData = data.subarray(offset, offset + imageLength);
+    if (imageData.length === 0)
+        return null;
+    return {
+        data: imageData,
+        mimeType: normalizeMimeType(mimeType),
+        width: width > 0 ? width : undefined,
+        height: height > 0 ? height : undefined,
+        pictureType,
+    };
+}
+/**
+ * Parse a Vorbis comment block
+ * Format: vendor string length (32-bit LE) + vendor string + comment count (32-bit LE) + comments
+ * Each comment: length (32-bit LE) + "FIELD=value"
+ */
+function parseVorbisCommentBlock(data) {
+    const comments = {};
+    if (data.length < 8)
+        return comments;
+    let offset = 0;
+    // Skip vendor string
+    const vendorLength = data.readUInt32LE(offset);
+    offset += 4 + vendorLength;
+    if (offset + 4 > data.length)
+        return comments;
+    // Read comment count
+    const commentCount = data.readUInt32LE(offset);
+    offset += 4;
+    // Read each comment
+    for (let i = 0; i < commentCount && offset + 4 <= data.length; i++) {
+        const commentLength = data.readUInt32LE(offset);
+        offset += 4;
+        if (offset + commentLength > data.length)
+            break;
+        const comment = data.toString('utf8', offset, offset + commentLength);
+        offset += commentLength;
+        // Split on first '='
+        const eqIndex = comment.indexOf('=');
+        if (eqIndex > 0) {
+            const field = comment.substring(0, eqIndex).toUpperCase();
+            const value = comment.substring(eqIndex + 1);
+            // Only store first value for each field
+            if (!comments[field]) {
+                comments[field] = value;
+            }
+        }
+    }
+    return comments;
+}
+/**
+ * Match a Vorbis comment field name against known field names
+ */
+function getFieldValue(comments, fieldNames) {
+    for (const name of fieldNames) {
+        const value = comments[name];
+        if (value)
+            return cleanText(value);
+    }
+    return undefined;
+}
+/**
+ * Extract metadata from a FLAC file
+ */
+export async function extractFromFlac(reader) {
+    // Verify FLAC signature
+    const signature = await reader.read(0, 4);
+    if (signature.toString('ascii') !== 'fLaC') {
+        return null;
+    }
+    const metadata = {};
+    let frontCover = null;
+    let anyArtwork = null;
+    let offset = 4;
+    let isLastBlock = false;
+    while (!isLastBlock && offset < reader.size) {
+        // Read metadata block header (4 bytes)
+        const blockHeader = await reader.read(offset, 4);
+        if (blockHeader.length < 4)
+            break;
+        isLastBlock = (blockHeader[0] & 0x80) !== 0;
+        const blockType = blockHeader[0] & 0x7f;
+        const blockLength = (blockHeader[1] << 16) | (blockHeader[2] << 8) | blockHeader[3];
+        if (blockLength <= 0 || offset + 4 + blockLength > reader.size)
+            break;
+        // Process metadata blocks
+        if (blockType === 4 /* MetadataBlockType.VORBIS_COMMENT */) {
+            const commentData = await reader.read(offset + 4, blockLength);
+            const comments = parseVorbisCommentBlock(commentData);
+            // Extract metadata from Vorbis comments
+            metadata.title = metadata.title ?? getFieldValue(comments, VORBIS_FIELDS.TITLE);
+            metadata.artist = metadata.artist ?? getFieldValue(comments, VORBIS_FIELDS.ARTIST);
+            metadata.album = metadata.album ?? getFieldValue(comments, VORBIS_FIELDS.ALBUM);
+            metadata.genre = metadata.genre ?? getFieldValue(comments, VORBIS_FIELDS.GENRE);
+            const dateValue = getFieldValue(comments, VORBIS_FIELDS.DATE);
+            if (dateValue && !metadata.year) {
+                metadata.year = parseYear(dateValue);
+            }
+            const bpmValue = getFieldValue(comments, VORBIS_FIELDS.BPM);
+            if (bpmValue && !metadata.bpm) {
+                metadata.bpm = parseBpm(bpmValue);
+            }
+            metadata.key = metadata.key ?? getFieldValue(comments, VORBIS_FIELDS.KEY);
+        }
+        else if (blockType === 6 /* MetadataBlockType.PICTURE */) {
+            const pictureData = await reader.read(offset + 4, blockLength);
+            const artwork = parsePictureBlock(pictureData);
+            if (artwork) {
+                if (artwork.pictureType === PictureType.FrontCover) {
+                    frontCover = artwork;
+                }
+                else if (!anyArtwork) {
+                    anyArtwork = artwork;
+                }
+            }
+        }
+        offset += 4 + blockLength;
+    }
+    // Use front cover if available, otherwise any artwork
+    const artwork = frontCover ?? anyArtwork;
+    if (artwork) {
+        metadata.artwork = artwork.data;
+        metadata.artworkMimeType = artwork.mimeType;
+    }
+    // Return null if no metadata was found
+    if (Object.keys(metadata).length === 0) {
+        return null;
+    }
+    return metadata;
+}
+//# sourceMappingURL=flac.js.map

package/dist/parsers/flac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flac.js","sourceRoot":"","sources":["../../src/parsers/flac.ts"],"names":[],"mappings":"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"}

package/dist/parsers/id3.d.ts

@@ -0,0 +1,6 @@
+import type { ExtractedMetadata, FileReader } from '../types.js';
+/**
+ * Extract metadata from an MP3 file with ID3v2 tags
+ */
+export declare function extractFromMp3(reader: FileReader): Promise<ExtractedMetadata | null>;
+//# sourceMappingURL=id3.d.ts.map

package/dist/parsers/id3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id3.d.ts","sourceRoot":"","sources":["../../src/parsers/id3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AA4IlF;;GAEG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAuG1F"}