@rafaelsilvadeveloper/fast-media-tags 1.0.2

package/README.md

@@ -0,0 +1,77 @@
+# @rafaelsilvadeveloper/fast-media-tags
+
+An ultra-lightweight, zero-dependency, and extremely fast binary ID3v2 tag parser for Node.js, Bun, Edge, and browser environments.
+
+[![NPM Version](https://img.shields.io/npm/v/@rafaelsilvadeveloper/fast-media-tags.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/fast-media-tags)
+[![Discord Support](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=flat-square)](https://discord.gg/7Fw7snafYS)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-blueviolet.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/fast-media-tags)
+
+## Features
+
+*   🚀 **High Performance**: Parses ID3 tags by reading only the first few Kilobytes of the audio file, saving memory, bandwidth, and CPU cycles.
+*   📦 **Zero Dependencies**: Pure TypeScript/JavaScript binary operations. Works out-of-the-box in Node.js, Bun, Edge/Serverless functions, and modern browsers.
+*   🖼️ **Album Art (APIC)**: Decodes cover photos (MIME type, format, type, description) and automatically exposes base64 and binary array data.
+*   🛡️ **TypeScript Definitions**: Strongly typed return signatures.
+
+## Installation
+
+```bash
+npm install @rafaelsilvadeveloper/fast-media-tags
+```
+
+## Usage
+
+### Reading tags from an ArrayBuffer
+
+```typescript
+import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';
+
+// In browser or bun
+const buffer = await file.arrayBuffer();
+const tags = await readAudioTags(buffer);
+
+console.log(tags.title);  // 'Synthwave Dreams'
+console.log(tags.artist); // 'CyberRunner'
+console.log(tags.album);  // 'Grid Horizons'
+```
+
+### Reading tags from a Blob / File (Browser or Bun)
+
+```typescript
+import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';
+
+// Directly pass a Blob or HTML5 File object
+const tags = await readAudioTags(fileBlob);
+if (tags.picture) {
+  console.log(`Album Art format: ${tags.picture.format}`);
+  // base64 ready for <img src="...">
+  const imageSrc = tags.picture.base64;
+}
+```
+
+### Reading tags from a local File Path (Node.js & Bun)
+
+```typescript
+import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';
+
+const tags = await readAudioTags('./music/track.mp3');
+console.log(`Title: ${tags.title}, Year: ${tags.year}`);
+```
+
+## Supported Tags
+
+*   `title` (`TIT2`)
+*   `artist` (`TPE1`)
+*   `album` (`TALB`)
+*   `year` (`TYER` or `TDRC`)
+*   `genre` (`TCON`)
+*   `picture` (`APIC`)
+
+## Support
+
+For support, questions, or discussions, join our Discord server:
+
+[![Discord Server](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=for-the-badge)](https://discord.gg/7Fw7snafYS)
+
+## License
+MIT

package/dist/fastMediaTags.d.ts

@@ -0,0 +1,5 @@
+import type { AudioTags } from './types';
+/**
+ * Parses ID3v2 tags from audio bytes or files.
+ */
+export declare function readAudioTags(file: Blob | ArrayBuffer | string): Promise<AudioTags>;

package/dist/fastMediaTags.js

@@ -0,0 +1,213 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAudioTags = readAudioTags;
+function readString(bytes, start, end, encoding) {
+    const slice = bytes.subarray(start, end);
+    if (encoding === 1 || encoding === 2) {
+        let offset = 0;
+        if (slice[0] === 0xff && slice[1] === 0xfe)
+            offset = 2; // UTF-16LE BOM
+        if (slice[0] === 0xfe && slice[1] === 0xff)
+            offset = 2; // UTF-16BE BOM
+        let str = '';
+        for (let i = offset; i < slice.length - 1; i += 2) {
+            const code = slice[i] | (slice[i + 1] << 8);
+            if (code === 0)
+                break;
+            str += String.fromCharCode(code);
+        }
+        return str;
+    }
+    else {
+        let str = '';
+        for (let i = 0; i < slice.length; i++) {
+            if (slice[i] === 0)
+                break;
+            str += String.fromCharCode(slice[i]);
+        }
+        try {
+            return decodeURIComponent(escape(str));
+        }
+        catch (_) {
+            return str;
+        }
+    }
+}
+function parseID3v2(buffer) {
+    const bytes = new Uint8Array(buffer);
+    if (bytes[0] !== 0x49 || bytes[1] !== 0x44 || bytes[2] !== 0x33) {
+        return {};
+    }
+    const version = bytes[3];
+    if (version < 3 || version > 4) {
+        return {};
+    }
+    const tagSize = ((bytes[6] & 0x7f) << 21) |
+        ((bytes[7] & 0x7f) << 14) |
+        ((bytes[8] & 0x7f) << 7) |
+        (bytes[9] & 0x7f);
+    const tags = {};
+    let offset = 10;
+    const tagEnd = Math.min(offset + tagSize, bytes.length);
+    while (offset < tagEnd - 10) {
+        const frameId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+        if (frameId.charCodeAt(0) === 0 || !/^[A-Z0-9]{4}$/.test(frameId)) {
+            break;
+        }
+        let frameSize = 0;
+        if (version === 3) {
+            frameSize =
+                (bytes[offset + 4] << 24) |
+                    (bytes[offset + 5] << 16) |
+                    (bytes[offset + 6] << 8) |
+                    bytes[offset + 7];
+        }
+        else {
+            frameSize =
+                ((bytes[offset + 4] & 0x7f) << 21) |
+                    ((bytes[offset + 5] & 0x7f) << 14) |
+                    ((bytes[offset + 6] & 0x7f) << 7) |
+                    (bytes[offset + 7] & 0x7f);
+        }
+        if (frameSize <= 0 || offset + 10 + frameSize > tagEnd) {
+            break;
+        }
+        const frameStart = offset + 10;
+        const frameEnd = frameStart + frameSize;
+        if (frameId.startsWith('T') && frameId !== 'TXXX') {
+            const encoding = bytes[frameStart];
+            const text = readString(bytes, frameStart + 1, frameEnd, encoding);
+            if (frameId === 'TIT2')
+                tags.title = text;
+            else if (frameId === 'TPE1')
+                tags.artist = text;
+            else if (frameId === 'TALB')
+                tags.album = text;
+            else if (frameId === 'TYER' || frameId === 'TDRC')
+                tags.year = text.substring(0, 4);
+            else if (frameId === 'TCON')
+                tags.genre = text;
+        }
+        else if (frameId === 'APIC') {
+            const encoding = bytes[frameStart];
+            let mimeEnd = frameStart + 1;
+            while (bytes[mimeEnd] !== 0 && mimeEnd < frameEnd)
+                mimeEnd++;
+            const format = String.fromCharCode(...bytes.subarray(frameStart + 1, mimeEnd));
+            const typeCode = bytes[mimeEnd + 1];
+            const type = getPictureType(typeCode);
+            let descEnd = mimeEnd + 2;
+            if (encoding === 1 || encoding === 2) {
+                while ((bytes[descEnd] !== 0 || bytes[descEnd + 1] !== 0) && descEnd < frameEnd - 1)
+                    descEnd += 2;
+                descEnd += 2;
+            }
+            else {
+                while (bytes[descEnd] !== 0 && descEnd < frameEnd)
+                    descEnd++;
+                descEnd += 1;
+            }
+            const description = readString(bytes, mimeEnd + 2, descEnd, encoding);
+            const imgData = bytes.subarray(descEnd, frameEnd);
+            let binary = '';
+            for (let i = 0; i < imgData.length; i++) {
+                binary += String.fromCharCode(imgData[i]);
+            }
+            const base64 = btoa(binary);
+            tags.picture = {
+                format,
+                type,
+                description,
+                data: new Uint8Array(imgData),
+                base64: `data:${format};base64,${base64}`,
+            };
+        }
+        offset = frameEnd;
+    }
+    return tags;
+}
+function getPictureType(code) {
+    const types = [
+        'Other',
+        '32x32 pixels file icon',
+        'Other file icon',
+        'Cover (front)',
+        'Cover (back)',
+        'Leaflet page',
+        'Media (e.g. label side of CD)',
+        'Lead artist/lead performer/soloist',
+        'Artist/performer',
+        'Conductor',
+        'Band/Orchestra',
+        'Composer',
+        'Lyricist/text writer',
+        'Recording Location',
+        'During recording',
+        'During performance',
+        'Movie/video screen capture',
+        'A bright coloured fish',
+        'Illustration',
+        'Band/artist logotype',
+        'Publisher/Studio logotype',
+    ];
+    return types[code] || 'Unknown';
+}
+/**
+ * Parses ID3v2 tags from audio bytes or files.
+ */
+async function readAudioTags(file) {
+    if (file instanceof ArrayBuffer) {
+        return parseID3v2(file);
+    }
+    if (typeof Blob !== 'undefined' && file instanceof Blob) {
+        const buffer = await file.slice(0, 131072).arrayBuffer();
+        return parseID3v2(buffer);
+    }
+    if (typeof file === 'string') {
+        try {
+            const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            const handle = await fs.open(file, 'r');
+            const buffer = Buffer.alloc(131072);
+            await handle.read(buffer, 0, 131072, 0);
+            await handle.close();
+            return parseID3v2(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+        }
+        catch (err) {
+            throw new Error(`Failed to read file path: ${err.message}`);
+        }
+    }
+    throw new Error('Unsupported file type. Expected Blob, ArrayBuffer, or file path string.');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { readAudioTags } from './fastMediaTags';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAudioTags = void 0;
+var fastMediaTags_1 = require("./fastMediaTags");
+Object.defineProperty(exports, "readAudioTags", { enumerable: true, get: function () { return fastMediaTags_1.readAudioTags; } });

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface AudioPicture {
+    format: string;
+    type: string;
+    description: string;
+    data: Uint8Array;
+    base64?: string;
+}
+export interface AudioTags {
+    title?: string;
+    artist?: string;
+    album?: string;
+    year?: string;
+    genre?: string;
+    picture?: AudioPicture;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rafaelsilvadeveloper/fast-media-tags",
+  "version": "1.0.2",
+  "description": "An ultra-lightweight, zero-dependency binary ID3v2 tag parser for Node/Bun/Edge, optimized for high speed and low memory.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafael-packages/fast-media-tags.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rafael-packages/fast-media-tags/issues"
+  },
+  "homepage": "https://github.com/rafael-packages/fast-media-tags#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "prepare": "bun run build",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts tests/**/*.ts"
+  },
+  "keywords": [
+    "id3",
+    "mp3",
+    "audio",
+    "tags",
+    "metadata",
+    "binary-parser",
+    "typescript"
+  ],
+  "author": "realkalashnikov",
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3"
+  }
+}