taglib-wasm 0.3.1 → 0.3.3

package/src/types.ts

@@ -1,5 +1,11 @@
 /**
  * @fileoverview TypeScript type definitions for taglib-wasm
+ *
+ * This module contains all the type definitions used throughout
+ * the taglib-wasm library, including metadata structures,
+ * audio properties, and format-specific mappings.
+ *
+ * @module taglib-wasm/types
  */
 
 // Re-export commonly used classes from other modules
@@ -7,12 +13,32 @@ export type { TagLibModule } from "./wasm.ts";
 // Note: AudioFile is not needed for JSR exports
 
 /**
- * Supported file types
+ * Supported file types detected by TagLib.
+ * "UNKNOWN" indicates the format could not be determined.
+ *
+ * @example
+ * ```typescript
+ * const file = await taglib.openFile(buffer);
+ * const format = file.getFormat();
+ * if (format === "MP3") {
+ *   // Handle MP3-specific features
+ * }
+ * ```
  */
-export type FileType = "MP3" | "MP4" | "FLAC" | "OGG" | "OPUS" | "WAV" | "AIFF" | "UNKNOWN";
+export type FileType =
+  | "MP3"
+  | "MP4"
+  | "FLAC"
+  | "OGG"
+  | "OPUS"
+  | "WAV"
+  | "AIFF"
+  | "UNKNOWN";
 
 /**
- * Audio format types supported by TagLib
+ * Audio format types supported by TagLib.
+ * More comprehensive than FileType, includes additional formats
+ * that TagLib can read but may have limited support.
  */
 export type AudioFormat =
   | "MP3"
@@ -34,7 +60,16 @@ export type AudioFormat =
   | "XM";
 
 /**
- * Audio properties containing technical information about the file
+ * Audio properties containing technical information about the file.
+ * All properties are read-only and represent the actual audio stream data.
+ *
+ * @example
+ * ```typescript
+ * const props = file.audioProperties();
+ * console.log(`Duration: ${props.length} seconds`);
+ * console.log(`Bitrate: ${props.bitrate} kbps`);
+ * console.log(`Sample rate: ${props.sampleRate} Hz`);
+ * ```
  */
 export interface AudioProperties {
   /** Length of the audio in seconds */
@@ -48,7 +83,20 @@ export interface AudioProperties {
 }
 
 /**
- * Basic metadata tags
+ * Basic metadata tags common to all audio formats.
+ * These are the standard fields supported by most audio files.
+ * All fields are optional as not all formats support all fields.
+ *
+ * @example
+ * ```typescript
+ * const tag: Tag = {
+ *   title: "Song Title",
+ *   artist: "Artist Name",
+ *   album: "Album Name",
+ *   year: 2025,
+ *   track: 5
+ * };
+ * ```
  */
 export interface Tag {
   /** Track title */
@@ -68,7 +116,21 @@ export interface Tag {
 }
 
 /**
- * Extended metadata with format-agnostic field names
+ * Extended metadata with format-agnostic field names.
+ * Includes advanced fields like MusicBrainz IDs, ReplayGain values,
+ * and other specialized metadata. Field availability depends on
+ * the audio format and existing metadata.
+ *
+ * @example
+ * ```typescript
+ * const extTag: ExtendedTag = {
+ *   ...basicTag,
+ *   albumArtist: "Various Artists",
+ *   musicbrainzTrackId: "123e4567-e89b-12d3-a456-426614174000",
+ *   replayGainTrackGain: "-6.54 dB",
+ *   bpm: 120
+ * };
+ * ```
  */
 export interface ExtendedTag extends Tag {
   /** AcoustID fingerprint (Chromaprint) */
@@ -120,7 +182,19 @@ export interface ExtendedTag extends Tag {
 }
 
 /**
- * Format-specific field mapping for automatic tag mapping
+ * Format-specific field mapping for automatic tag mapping.
+ * Defines how a metadata field maps to different audio formats.
+ * Used internally for format-agnostic metadata operations.
+ *
+ * @example
+ * ```typescript
+ * const artistMapping: FieldMapping = {
+ *   id3v2: { frame: "TPE1" },
+ *   vorbis: "ARTIST",
+ *   mp4: "©ART",
+ *   wav: "IART"
+ * };
+ * ```
  */
 export interface FieldMapping {
   /** MP3 ID3v2 mapping */
@@ -137,7 +211,19 @@ export interface FieldMapping {
 }
 
 /**
- * Complete metadata field mappings for all formats
+ * Complete metadata field mappings for all formats.
+ * This constant defines how each ExtendedTag field maps to
+ * format-specific metadata fields across different audio formats.
+ * Used for automatic tag mapping in format-agnostic operations.
+ *
+ * @example
+ * ```typescript
+ * // Get the ID3v2 frame for the artist field
+ * const artistFrame = METADATA_MAPPINGS.artist.id3v2?.frame; // "TPE1"
+ *
+ * // Get the Vorbis comment field for album artist
+ * const vorbisField = METADATA_MAPPINGS.albumArtist.vorbis; // "ALBUMARTIST"
+ * ```
  */
 export const METADATA_MAPPINGS: Record<keyof ExtendedTag, FieldMapping> = {
   // Basic fields (already handled by TagLib's standard API)
@@ -297,14 +383,41 @@ export const METADATA_MAPPINGS: Record<keyof ExtendedTag, FieldMapping> = {
 };
 
 /**
- * Extended metadata properties map
+ * Extended metadata properties map.
+ * A flexible key-value structure where each key can have multiple values.
+ * Used for accessing all metadata in a file, including non-standard fields.
+ *
+ * @example
+ * ```typescript
+ * const properties: PropertyMap = {
+ *   "ARTIST": ["Artist Name"],
+ *   "ALBUMARTIST": ["Album Artist"],
+ *   "MUSICBRAINZ_TRACKID": ["123e4567-e89b-12d3-a456-426614174000"]
+ * };
+ * ```
  */
 export interface PropertyMap {
   [key: string]: string[];
 }
 
 /**
- * Picture/artwork data
+ * Re-export TagName type from constants
+ */
+export type { TagName } from "./constants.ts";
+
+/**
+ * Picture/artwork data embedded in audio files.
+ * Represents album art, artist photos, or other images.
+ *
+ * @example
+ * ```typescript
+ * const picture: Picture = {
+ *   mimeType: "image/jpeg",
+ *   data: new Uint8Array(imageBuffer),
+ *   type: PictureType.FrontCover,
+ *   description: "Album cover"
+ * };
+ * ```
  */
 export interface Picture {
   /** MIME type of the image */
@@ -318,7 +431,19 @@ export interface Picture {
 }
 
 /**
- * Picture types as defined by ID3v2 APIC frame
+ * Picture types as defined by ID3v2 APIC frame.
+ * Standard picture type codes used across different formats
+ * to categorize embedded images.
+ *
+ * @example
+ * ```typescript
+ * // Set front cover art
+ * const coverArt = {
+ *   type: PictureType.FrontCover,
+ *   mimeType: "image/jpeg",
+ *   data: imageData
+ * };
+ * ```
  */
 export enum PictureType {
   Other = 0,
@@ -345,16 +470,24 @@ export enum PictureType {
 }
 
 /**
- * Bitrate control modes for audio encoding (MP4/M4A specific)
+ * Bitrate control modes for audio encoding (MP4/M4A specific).
+ * Indicates how the audio was encoded in terms of bitrate management.
+ *
+ * - Constant: Fixed bitrate throughout the file
+ * - LongTermAverage: Average bitrate over time
+ * - VariableConstrained: Variable within limits
+ * - Variable: Fully variable bitrate
  */
-export type BitrateControlMode = 
+export type BitrateControlMode =
   | "Constant"
-  | "LongTermAverage" 
+  | "LongTermAverage"
   | "VariableConstrained"
   | "Variable";
 
 /**
- * Map of bitrate control mode names to their numeric values
+ * Map of bitrate control mode names to their numeric values.
+ * Used for converting between string representations and numeric codes
+ * stored in MP4/M4A files.
  */
 export const BITRATE_CONTROL_MODE_VALUES: Record<BitrateControlMode, number> = {
   Constant: 0,
@@ -364,7 +497,9 @@ export const BITRATE_CONTROL_MODE_VALUES: Record<BitrateControlMode, number> = {
 };
 
 /**
- * Map of numeric values to bitrate control mode names
+ * Map of numeric values to bitrate control mode names.
+ * Used for converting numeric codes from MP4/M4A files
+ * to human-readable string representations.
  */
 export const BITRATE_CONTROL_MODE_NAMES: Record<number, BitrateControlMode> = {
   0: "Constant",
@@ -374,7 +509,21 @@ export const BITRATE_CONTROL_MODE_NAMES: Record<number, BitrateControlMode> = {
 };
 
 /**
- * Configuration options for TagLib initialization
+ * Configuration options for TagLib initialization.
+ * Allows customization of memory limits and debug settings.
+ *
+ * @example
+ * ```typescript
+ * const config: TagLibConfig = {
+ *   memory: {
+ *     initial: 16 * 1024 * 1024,  // 16MB
+ *     maximum: 64 * 1024 * 1024   // 64MB
+ *   },
+ *   debug: true
+ * };
+ *
+ * const taglib = await TagLibWorkers.initialize(wasmBinary, config);
+ * ```
  */
 export interface TagLibConfig {
   /** Memory allocation settings */

package/src/wasm-workers.ts

@@ -23,7 +23,7 @@ const DEFAULT_WORKERS_CONFIG: Required<TagLibConfig> = {
  * Load and initialize the TagLib WebAssembly module for Cloudflare Workers
  *
  * @param wasmBinary - The WebAssembly binary as Uint8Array
- * @param config - Optional configuration for the WASM module
+ * @param config - Optional configuration for the Wasm module
  * @returns Promise resolving to initialized TagLib module
  *
  * @example
@@ -66,13 +66,13 @@ export async function loadTagLibModuleForWorkers(
   try {
     // For Workers, we need to use a modified version of the Emscripten output
     // that doesn't include Node.js/CommonJS dependencies
-    const TagLibWASM = await createWorkersCompatibleModule();
+    const TagLibWasm = await createWorkersCompatibleModule();
 
-    if (typeof TagLibWASM !== "function") {
+    if (typeof TagLibWasm !== "function") {
       throw new Error("Failed to load taglib-wasm module for Workers");
     }
 
-    const wasmInstance = await TagLibWASM(moduleConfig);
+    const wasmInstance = await TagLibWasm(moduleConfig);
 
     // Ensure proper memory arrays are set up
     if (!wasmInstance.HEAPU8) {
@@ -99,7 +99,7 @@ export async function loadTagLibModuleForWorkers(
 
 /**
  * Create a Workers-compatible version of the Emscripten module
- * This function loads the WASM module without Node.js/CommonJS dependencies
+ * This function loads the Wasm module without Node.js/CommonJS dependencies
  */
 async function createWorkersCompatibleModule(): Promise<any> {
   // In a real Workers environment, you would typically:
@@ -115,8 +115,8 @@ async function createWorkersCompatibleModule(): Promise<any> {
   } catch (error) {
     // If that fails, provide a fallback implementation
     throw new Error(
-      "Workers-compatible WASM module not available. " +
-        "Please build with Workers target or use a bundler that supports WASM modules. " +
+      "Workers-compatible Wasm module not available. " +
+        "Please build with Workers target or use a bundler that supports Wasm modules. " +
         `Original error: ${(error as Error).message}`,
     );
   }
@@ -141,7 +141,7 @@ export function cStringToJS(module: TagLibModule, ptr: number): string {
 export function jsToCString(module: TagLibModule, str: string): number {
   const encoder = new TextEncoder();
   const bytes = encoder.encode(str + "\0");
-  
+
   // Use allocate if available, otherwise use _malloc
   if (module.allocate && module.ALLOC_NORMAL !== undefined) {
     return module.allocate(bytes, module.ALLOC_NORMAL);

package/src/wasm.ts

@@ -13,20 +13,29 @@ export interface EmscriptenModule {
   HEAPU32: Uint32Array;
   HEAPF32: Float32Array;
   HEAPF64: Float64Array;
-  
+
   // Memory management
   _malloc(size: number): number;
   _free(ptr: number): void;
   allocate?(data: number[] | Uint8Array, allocator: number): number;
   ALLOC_NORMAL?: number;
-  
+
   // String conversion
-  ccall?(ident: string, returnType: string, argTypes: string[], args: any[]): any;
-  cwrap?(ident: string, returnType: string, argTypes: string[]): (...args: any[]) => any;
-  
+  ccall?(
+    ident: string,
+    returnType: string,
+    argTypes: string[],
+    args: any[],
+  ): any;
+  cwrap?(
+    ident: string,
+    returnType: string,
+    argTypes: string[],
+  ): (...args: any[]) => any;
+
   // File system (if enabled)
   FS?: any;
-  
+
   // Runtime
   then?(callback: (module: EmscriptenModule) => void): void;
   onRuntimeInitialized?: () => void;
@@ -80,10 +89,10 @@ export interface TagLibModule extends EmscriptenModule {
   FileHandle: new () => FileHandle;
   TagWrapper: new () => TagWrapper;
   AudioPropertiesWrapper: new () => AudioPropertiesWrapper;
-  
+
   // Embind functions
   createFileHandle(): FileHandle;
-  
+
   // C-style functions (optional - used by Workers API)
   _taglib_file_new_from_buffer?(ptr: number, size: number): number;
   _taglib_file_delete?(fileId: number): void;
@@ -92,7 +101,7 @@ export interface TagLibModule extends EmscriptenModule {
   _taglib_file_tag?(fileId: number): number;
   _taglib_file_audioproperties?(fileId: number): number;
   _taglib_file_save?(fileId: number): number;
-  
+
   _taglib_tag_title?(tagPtr: number): number;
   _taglib_tag_artist?(tagPtr: number): number;
   _taglib_tag_album?(tagPtr: number): number;
@@ -100,7 +109,7 @@ export interface TagLibModule extends EmscriptenModule {
   _taglib_tag_genre?(tagPtr: number): number;
   _taglib_tag_year?(tagPtr: number): number;
   _taglib_tag_track?(tagPtr: number): number;
-  
+
   _taglib_tag_set_title?(tagPtr: number, titlePtr: number): void;
   _taglib_tag_set_artist?(tagPtr: number, artistPtr: number): void;
   _taglib_tag_set_album?(tagPtr: number, albumPtr: number): void;
@@ -108,7 +117,7 @@ export interface TagLibModule extends EmscriptenModule {
   _taglib_tag_set_genre?(tagPtr: number, genrePtr: number): void;
   _taglib_tag_set_year?(tagPtr: number, year: number): void;
   _taglib_tag_set_track?(tagPtr: number, track: number): void;
-  
+
   _taglib_audioproperties_length?(propsPtr: number): number;
   _taglib_audioproperties_bitrate?(propsPtr: number): number;
   _taglib_audioproperties_samplerate?(propsPtr: number): number;
@@ -121,4 +130,4 @@ export interface WasmModule extends EmscriptenModule {
   createFileHandle?(): FileHandle;
 }
 
-// Module loading function removed for modular imports
+// Module loading function removed for modular imports