taglib-wasm 0.5.2 → 0.9.0

package/README.md

@@ -1,7 +1,7 @@
 # TagLib-Wasm
 
 [![Tests](https://github.com/CharlesWiltgen/taglib-wasm/actions/workflows/test.yml/badge.svg)](https://github.com/CharlesWiltgen/taglib-wasm/actions/workflows/test.yml)
-[![npm version](https://img.shields.io/npm/v/taglib-wasm.svg?logo=nodedotjs&logoColor=f5f5f5)](https://www.npmjs.com/package/taglib-wasm)
+[![npm version](https://img.shields.io/npm/v/taglib-wasm.svg)](https://www.npmjs.com/package/taglib-wasm)
 [![npm downloads](https://img.shields.io/npm/dm/taglib-wasm.svg)](https://www.npmjs.com/package/taglib-wasm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/CharlesWiltgen/taglib-wasm/blob/main/LICENSE)
 <br>[![Built with](https://img.shields.io/badge/TypeScript-5-3178c6.svg?logo=typescript&logoColor=f5f5f5)](https://www.typescriptlang.org/)
@@ -29,24 +29,26 @@ TagLib-Wasm stands on the shoulders of giants, including
 [Wasm](https://webassembly.org/) ([WebAssembly](https://webassembly.org/)).
 TagLib itself is legendary, and a core dependency of many music apps.
 
-## 🎯 Features
+## Features
 
-- **✅ Full audio format support** – Supports all audio formats supported by
-  TagLib
-- **✅ TypeScript first** – Complete type definitions and modern API
-- **✅ Wide TS/JS runtime support** – Deno, Node.js, Bun, Electron, Cloudflare
+- **Blazing fast performance** – Batch processing delivers 10-20x speedup for
+  multiple files
+- **Full audio format support** – Supports all audio formats supported by TagLib
+- **TypeScript first** – Complete type definitions and modern API
+- **Wide TS/JS runtime support** – Deno, Node.js, Bun, Electron, Cloudflare
   Workers, and browsers
-- **✅ Format abstraction** – Handles container format details automagically
-  when possible
-- **✅ Zero dependencies** – Self-contained Wasm bundle
-- **✅ Production ready** – Growing test suite helps ensure safety and
-  reliability
-- **✅ Two API styles** – Use the “Simple” API (3 functions), or the full “Core”
+- **Format abstraction** – Handles container format details automagically when
+  possible
+- **Zero dependencies** – Self-contained Wasm bundle
+- **Automatic runtime optimization** – Uses WASI for Deno/Node.js, Emscripten
+  for browsers
+- **Production ready** – Growing test suite helps ensure safety and reliability
+- **Two API styles** – Use the "Simple" API (3 functions), or the full "Core"
   API for more advanced applications
-- **✅ Batch folder operations** – Scan directories, process multiple files,
-  find duplicates, and export metadata catalogs
+- **Batch folder operations** – Scan directories, process multiple files, find
+  duplicates, and export metadata catalogs
 
-## 📦 Installation
+## Installation
 
 ### Deno
 
@@ -118,7 +120,7 @@ const wasmBinary = await Deno.readFile(
 const taglib = await TagLib.initialize({ wasmBinary });
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Simple API
 
@@ -143,6 +145,25 @@ await updateTags("song.mp3", {
 });
 ```
 
+### High-Performance Batch Processing
+
+```typescript
+import { readMetadataBatch, readTagsBatch } from "taglib-wasm/simple";
+
+// Process multiple files in parallel - dramatically faster!
+const files = ["track01.mp3", "track02.mp3", /* ... */ "track20.mp3"];
+
+// Read just tags (18x faster than sequential)
+const tags = await readTagsBatch(files, { concurrency: 8 });
+
+// Read complete metadata including cover art detection (15x faster)
+const metadata = await readMetadataBatch(files, { concurrency: 8 });
+
+// Real-world performance:
+// Sequential: ~100 seconds for 20 files
+// Batch: ~5 seconds for 20 files (20x speedup!)
+```
+
 ### Full API
 
 The Full API might be a better choice for apps and utilities focused on advanced
@@ -216,6 +237,30 @@ const modifiedBuffer = await setCoverArt("song.mp3", imageData, "image/jpeg");
 // Save modifiedBuffer to file if needed
 ```
 
+### Working with Ratings
+
+```typescript
+import { RatingUtils, TagLib } from "taglib-wasm";
+
+const taglib = await TagLib.initialize();
+const file = await taglib.open("song.mp3");
+
+// Read rating (normalized 0.0-1.0)
+const rating = file.getRating();
+if (rating !== undefined) {
+  console.log(`Rating: ${RatingUtils.toStars(rating)} stars`);
+}
+
+// Set rating (4 out of 5 stars)
+file.setRating(0.8);
+file.save();
+
+file.dispose();
+```
+
+See the [Track Ratings Guide](https://charleswiltgen.github.io/taglib-wasm/guide/ratings.html)
+for RatingUtils API and cross-format conversion details.
+
 ### Container Format and Codec Detection
 
 ```typescript
@@ -247,9 +292,9 @@ Supported formats:
 - **WAV** – Container for PCM (uncompressed) audio
 - **AIFF** – Container for PCM (uncompressed) audio
 
-## 📚 Documentation
+## Documentation
 
-**[📖 View Full Documentation](https://charleswiltgen.github.io/taglib-wasm/)**
+**[View Full Documentation](https://charleswiltgen.github.io/taglib-wasm/)**
 
 ### Getting Started
 
@@ -260,8 +305,11 @@ Supported formats:
 ### Guides
 
 - [API Reference](https://charleswiltgen.github.io/taglib-wasm/api/)
+- [Performance Guide](https://charleswiltgen.github.io/taglib-wasm/concepts/performance.html)
+- [Album Processing Guide](https://charleswiltgen.github.io/taglib-wasm/guide/album-processing.html) - Process entire albums in seconds
 - [Platform Examples](https://charleswiltgen.github.io/taglib-wasm/guide/platform-examples.html)
 - [Working with Cover Art](https://charleswiltgen.github.io/taglib-wasm/guide/cover-art.html)
+- [Track Ratings](https://charleswiltgen.github.io/taglib-wasm/guide/ratings.html)
 - [Cloudflare Workers Setup](https://charleswiltgen.github.io/taglib-wasm/guide/workers-setup.html)
 - [Error Handling](https://charleswiltgen.github.io/taglib-wasm/concepts/error-handling.html)
 
@@ -271,19 +319,19 @@ Supported formats:
 - [Future Improvements](https://charleswiltgen.github.io/taglib-wasm/development/improvements.html)
 - [Contributing](CONTRIBUTING.md)
 
-## 📋 Supported Formats
+## Supported Formats
 
 `taglib-wasm` is designed to support all formats supported by TagLib:
 
-- ✅ **.mp3** – ID3v2 and ID3v1 tags
-- ✅ **.m4a/.mp4** – MPEG-4/AAC metadata for AAC and Apple Lossless audio
-- ✅ **.flac** – Vorbis comments and audio properties
-- ✅ **.ogg** – Ogg Vorbis format with full metadata support
-- ✅ **.wav** – INFO chunk metadata
-- ✅ **Additional formats** – Opus, APE, MPC, WavPack, TrueAudio, AIFF, WMA, and
+- **.mp3** – ID3v2 and ID3v1 tags
+- **.m4a/.mp4** – MPEG-4/AAC metadata for AAC and Apple Lossless audio
+- **.flac** – Vorbis comments and audio properties
+- **.ogg** – Ogg Vorbis format with full metadata support
+- **.wav** – INFO chunk metadata
+- **Additional formats** – Opus, APE, MPC, WavPack, TrueAudio, AIFF, WMA, and
   more
 
-## 🎯 Key Features
+## Key Features
 
 ### Extended Metadata Support
 
@@ -311,7 +359,7 @@ file.setProperty(Tags.TrackPeak, "0.987654");
 
 [View all supported tag constants →](https://charleswiltgen.github.io/taglib-wasm/api/tag-name-constants.html)
 
-## ⚡ Performance & Best Practices
+## Performance and Best Practices
 
 ### Batch Processing for Multiple Files
 
@@ -386,7 +434,7 @@ const taglib = await TagLib.initialize({ wasmBinary });
 
 [View complete performance guide →](https://charleswiltgen.github.io/taglib-wasm/concepts/performance.html)
 
-## 🏗️ Development
+## Development
 
 ### Build from Source
 
@@ -407,20 +455,20 @@ npm test
 
 [View full development guide →](CONTRIBUTING.md)
 
-## 🌐 Runtime Compatibility
+## Runtime Compatibility
 
 `taglib-wasm` works across all major JavaScript runtimes:
 
-| Runtime                | Status  | Installation              | Notes                     |
-| ---------------------- | ------- | ------------------------- | ------------------------- |
-| **Deno**               | ✅ Full | `npm:taglib-wasm`         | Native TypeScript         |
-| **Node.js**            | ✅ Full | `npm install taglib-wasm` | TypeScript via tsx        |
-| **Bun**                | ✅ Full | `bun add taglib-wasm`     | Native TypeScript         |
-| **Browser**            | ✅ Full | Via bundler               | Full API support          |
-| **Cloudflare Workers** | ✅ Full | `taglib-wasm/workers`     | Memory-optimized build    |
-| **Electron**           | ✅ Full | `npm install taglib-wasm` | Main & renderer processes |
+| Runtime                | Status | Installation              | Notes                     |
+| ---------------------- | ------ | ------------------------- | ------------------------- |
+| **Deno**               | Full   | `npm:taglib-wasm`         | Native TypeScript         |
+| **Node.js**            | Full   | `npm install taglib-wasm` | TypeScript via tsx        |
+| **Bun**                | Full   | `bun add taglib-wasm`     | Native TypeScript         |
+| **Browser**            | Full   | Via bundler               | Full API support          |
+| **Cloudflare Workers** | Full   | `taglib-wasm/workers`     | Memory-optimized build    |
+| **Electron**           | Full   | `npm install taglib-wasm` | Main & renderer processes |
 
-## 🚧 Known Limitations
+## Known Limitations
 
 - **Memory Usage** – Entire file must be loaded into memory (may be an issue for
   very large files)
@@ -429,12 +477,12 @@ npm test
 - **Cloudflare Workers** – Limited to 128MB memory per request; files larger
   than ~100MB may fail
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
 for details on our code of conduct and the process for submitting pull requests.
 
-## 📄 License
+## License
 
 This project uses dual licensing:
 
@@ -452,7 +500,8 @@ means:
 
 For details, see [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL)
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 - [TagLib](https://taglib.org/) – Excellent audio metadata library
 - [Emscripten](https://emscripten.org/) – WebAssembly compilation toolchain
+- [WASI](https://wasi.dev/) – WebAssembly System Interface for server-side runtimes

package/dist/index.d.ts

@@ -39,6 +39,7 @@
  * @see {@link createTagLib} - Factory function for creating TagLib instances
  */
 export { AudioFileImpl as AudioFile, createTagLib, TagLib, } from "./src/taglib.ts";
+export type { AudioFile as AudioFileInterface } from "./src/taglib.ts";
 /**
  * Error types for proper error handling and debugging.
  * @see {@link TagLibError} - Base error class for all TagLib errors
@@ -81,6 +82,7 @@ export { addPicture, applyPictures, applyTags, type BatchOptions, type BatchResu
  * @see {@link FormatMappings} - Format-specific field mappings (deprecated)
  */
 export { FormatMappings, getAllProperties, getAllPropertyKeys, getAllTagNames, getPropertiesByFormat, getPropertyMetadata, isValidProperty, isValidTagName, PROPERTIES, Tags, } from "./src/constants.ts";
+export type { PropertyMetadata } from "./src/constants/property-types.ts";
 /**
  * File I/O utilities for cover art operations.
  * @see {@link exportCoverArt} - Export cover art to file
@@ -95,7 +97,7 @@ export { copyCoverArt, exportAllPictures, exportCoverArt, exportPictureByType, f
  * @see {@link findDuplicates} - Find duplicate files based on metadata
  * @see {@link exportFolderMetadata} - Export folder metadata to JSON
  */
-export { type AudioFileMetadata, exportFolderMetadata, findDuplicates, type FolderScanOptions, type FolderScanResult, scanFolder, updateFolderTags, } from "./src/folder-api.ts";
+export { type AudioDynamics, type AudioFileMetadata, exportFolderMetadata, findDuplicates, type FolderScanOptions, type FolderScanResult, scanFolder, updateFolderTags, } from "./src/folder-api.ts";
 /**
  * Web browser utilities for cover art operations.
  * @see {@link pictureToDataURL} - Convert picture to data URL
@@ -114,20 +116,42 @@ export { canvasToPicture, createPictureDownloadURL, createPictureGallery, dataUR
  * @see {@link PropertyKey} - Type-safe property keys with autocomplete
  * @see {@link PropertyValue} - Type-safe property values
  */
-export type { AudioFormat, AudioProperties, ExtendedTag, FieldMapping, FileType, Picture, PropertyMap, Tag, TagName, } from "./src/types.ts";
+export type { AudioFileInput, AudioFormat, AudioProperties, ExtendedTag, FieldMapping, FileType, Picture, PropertyMap, Tag, TagName, } from "./src/types.ts";
 export type { PropertyKey, PropertyValue } from "./src/constants.ts";
 /**
  * Type and constant exports
  */
 export type { PictureType } from "./src/types.ts";
 export { PICTURE_TYPE_NAMES, PICTURE_TYPE_VALUES } from "./src/types.ts";
+/**
+ * Complex property types and constants for structured metadata.
+ * @see {@link COMPLEX_PROPERTIES} - Rich metadata object with format mappings
+ * @see {@link COMPLEX_PROPERTY_KEY} - Simple key map for daily use
+ * @see {@link Rating} - Track rating metadata (normalized 0.0-1.0)
+ * @see {@link UnsyncedLyrics} - Unsynchronized lyrics text
+ * @see {@link ComplexPropertyValueMap} - Type map for generic methods
+ */
+export { COMPLEX_PROPERTIES, COMPLEX_PROPERTY_KEY, } from "./src/constants/complex-properties.ts";
+export type { ComplexPropertyKey, ComplexPropertyKeyMap, ComplexPropertyValueMap, Rating, UnsyncedLyrics, VariantMap, } from "./src/constants/complex-properties.ts";
+/**
+ * Rating conversion utilities for cross-format compatibility.
+ * @see {@link RatingUtils} - Namespace with all rating utilities
+ * @see {@link toNormalized} - POPM (0-255) to normalized (0.0-1.0)
+ * @see {@link fromNormalized} - Normalized to POPM
+ * @see {@link toStars} - Normalized to star rating
+ * @see {@link fromStars} - Star rating to normalized
+ * @see {@link toPopm} - Normalized to standard POPM value
+ * @see {@link fromPopm} - Standard POPM to normalized
+ */
+export { clamp as clampRating, fromNormalized, fromPercent, fromPopm, fromStars, isValid as isValidRating, RatingUtils, toNormalized, toPercent, toPopm, toStars, } from "./src/utils/rating.ts";
 /**
  * Worker pool exports for parallel processing.
  * @see {@link TagLibWorkerPool} - Worker pool for parallel file processing
- * @see {@link getGlobalWorkerPool} - Get/create global worker pool instance
+ * @see {@link createWorkerPool} - Create and initialize a worker pool
+ * @see {@link getGlobalWorkerPool} - Get/create global worker pool instance (deprecated)
  * @see {@link terminateGlobalWorkerPool} - Terminate global worker pool
  */
-export { getGlobalWorkerPool, TagLibWorkerPool, terminateGlobalWorkerPool, } from "./src/worker-pool.ts";
+export { createWorkerPool, getGlobalWorkerPool, TagLibWorkerPool, terminateGlobalWorkerPool, } from "./src/worker-pool.ts";
 export type { BatchOperation, WorkerPoolOptions, WorkerTask, } from "./src/worker-pool.ts";
 /**
  * Wasm module types for advanced usage.
@@ -139,34 +163,34 @@ import type { TagLibModule } from "./src/wasm.ts";
 /**
  * Configuration options for loading the TagLib WASM module
  */
-export interface LoadTagLibOptions {
-    /**
-     * Optional pre-loaded WASM binary data.
-     * If provided, this will be used instead of fetching from network.
-     */
-    wasmBinary?: ArrayBuffer | Uint8Array;
-    /**
-     * Optional custom URL or path for the WASM file.
-     * This is passed to the locateFile function.
-     */
-    wasmUrl?: string;
-}
+export type { LoadTagLibOptions } from "./src/runtime/loader-types.ts";
+import type { LoadTagLibOptions } from "./src/runtime/loader-types.ts";
 /**
  * Load the TagLib Wasm module.
  * This function initializes the WebAssembly module and returns
  * the loaded module for use with the Full API.
  *
- * @param config - Optional configuration for module initialization
+ * Automatically selects the optimal implementation:
+ * - WASI for Deno/Node.js (faster filesystem access, MessagePack serialization)
+ * - Emscripten for browsers (universal compatibility)
+ *
+ * @param options - Optional configuration for module initialization
  * @returns Promise resolving to the initialized TagLib module
  *
  * @example
  * ```typescript
  * import { loadTagLibModule, createTagLib } from "taglib-wasm";
  *
- * // Manual module loading for advanced configuration
+ * // Auto-select optimal implementation
  * const module = await loadTagLibModule();
  * const taglib = await createTagLib(module);
  *
+ * // Force Emscripten mode
+ * const module = await loadTagLibModule({ legacyMode: true });
+ *
+ * // Force WASI mode (Deno/Node.js only)
+ * const module = await loadTagLibModule({ forceWasmType: "wasi" });
+ *
  * // With custom WASM binary
  * const wasmData = await fetch("taglib.wasm").then(r => r.arrayBuffer());
  * const module = await loadTagLibModule({ wasmBinary: wasmData });

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -85,11 +85,49 @@ import {
 } from "./src/web-utils.js";
 import { PICTURE_TYPE_NAMES, PICTURE_TYPE_VALUES } from "./src/types.js";
 import {
+  COMPLEX_PROPERTIES,
+  COMPLEX_PROPERTY_KEY
+} from "./src/constants/complex-properties.js";
+import {
+  clamp,
+  fromNormalized,
+  fromPercent,
+  fromPopm,
+  fromStars,
+  isValid,
+  RatingUtils,
+  toNormalized,
+  toPercent,
+  toPopm,
+  toStars
+} from "./src/utils/rating.js";
+import {
+  createWorkerPool,
   getGlobalWorkerPool,
   TagLibWorkerPool,
   terminateGlobalWorkerPool
 } from "./src/worker-pool.js";
 async function loadTagLibModule(options) {
+  if (options?.legacyMode) {
+    return loadLegacyTagLibModule(options);
+  }
+  try {
+    const { loadUnifiedTagLibModule } = await import("./src/runtime/unified-loader.js");
+    return await loadUnifiedTagLibModule({
+      wasmBinary: options?.wasmBinary,
+      wasmUrl: options?.wasmUrl,
+      // These options exist in the v2 loader
+      debug: false,
+      useInlineWasm: false
+    });
+  } catch (error) {
+    console.warn(
+      `[TagLib] Unified loader failed, falling back to legacy mode: ${error}`
+    );
+    return loadLegacyTagLibModule(options || {});
+  }
+}
+async function loadLegacyTagLibModule(options) {
   let createTagLibModule;
   try {
     const module2 = await import("./taglib-wrapper.js");
@@ -121,6 +159,8 @@ async function loadTagLibModule(options) {
 }
 export {
   AudioFileImpl as AudioFile,
+  COMPLEX_PROPERTIES,
+  COMPLEX_PROPERTY_KEY,
   EnvironmentError,
   FileOperationError,
   FormatMappings,
@@ -130,6 +170,7 @@ export {
   PICTURE_TYPE_NAMES,
   PICTURE_TYPE_VALUES,
   PROPERTIES,
+  RatingUtils,
   SUPPORTED_FORMATS,
   TagLib,
   TagLibError,
@@ -141,12 +182,14 @@ export {
   applyPictures,
   applyTags,
   canvasToPicture,
+  clamp as clampRating,
   clearPictures,
   clearTags,
   copyCoverArt,
   createPictureDownloadURL,
   createPictureGallery,
   createTagLib,
+  createWorkerPool,
   dataURLToPicture,
   displayPicture,
   exportAllPictures,
@@ -156,6 +199,10 @@ export {
   findCoverArtFiles,
   findDuplicates,
   findPictureByType,
+  fromNormalized,
+  fromPercent,
+  fromPopm,
+  fromStars,
   getAllProperties,
   getAllPropertyKeys,
   getAllTagNames,
@@ -177,6 +224,7 @@ export {
   isUnsupportedFormatError,
   isValidAudioFile,
   isValidProperty,
+  isValid as isValidRating,
   isValidTagName,
   loadPictureFromFile,
   loadTagLibModule,
@@ -194,6 +242,10 @@ export {
   setCoverArtFromCanvas,
   setWorkerPoolMode,
   terminateGlobalWorkerPool,
+  toNormalized,
+  toPercent,
+  toPopm,
+  toStars,
   updateFolderTags,
   updateTags
 };

package/dist/src/constants/basic-properties.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Basic audio metadata properties supported across all common formats.
+ * These are the core tags that most audio files should have.
+ */
+export declare const BASIC_PROPERTIES: {
+    readonly TITLE: {
+        readonly key: "TITLE";
+        readonly description: "The title of the track";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TIT2";
+            };
+            readonly vorbis: "TITLE";
+            readonly mp4: "©nam";
+            readonly wav: "INAM";
+        };
+    };
+    readonly ARTIST: {
+        readonly key: "ARTIST";
+        readonly description: "The primary performer(s) of the track";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TPE1";
+            };
+            readonly vorbis: "ARTIST";
+            readonly mp4: "©ART";
+            readonly wav: "IART";
+        };
+    };
+    readonly ALBUM: {
+        readonly key: "ALBUM";
+        readonly description: "The album/collection name";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TALB";
+            };
+            readonly vorbis: "ALBUM";
+            readonly mp4: "©alb";
+            readonly wav: "IPRD";
+        };
+    };
+    readonly DATE: {
+        readonly key: "DATE";
+        readonly description: "The date of recording (typically year)";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TDRC";
+            };
+            readonly vorbis: "DATE";
+            readonly mp4: "©day";
+            readonly wav: "ICRD";
+        };
+    };
+    readonly TRACKNUMBER: {
+        readonly key: "TRACKNUMBER";
+        readonly description: "The track number within the album";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TRCK";
+            };
+            readonly vorbis: "TRACKNUMBER";
+            readonly mp4: "trkn";
+            readonly wav: "ITRK";
+        };
+    };
+    readonly GENRE: {
+        readonly key: "GENRE";
+        readonly description: "The musical genre";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "TCON";
+            };
+            readonly vorbis: "GENRE";
+            readonly mp4: "©gen";
+            readonly wav: "IGNR";
+        };
+    };
+    readonly COMMENT: {
+        readonly key: "COMMENT";
+        readonly description: "Comments or notes about the track";
+        readonly type: "string";
+        readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "WAV"];
+        readonly mappings: {
+            readonly id3v2: {
+                readonly frame: "COMM";
+            };
+            readonly vorbis: "COMMENT";
+            readonly mp4: "©cmt";
+            readonly wav: "ICMT";
+        };
+    };
+};
+//# sourceMappingURL=basic-properties.d.ts.map

package/dist/src/constants/basic-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-properties.d.ts","sourceRoot":"","sources":["../../../src/constants/basic-properties.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsFnB,CAAC"}