taglib-wasm 0.3.3 → 0.3.9

package/src/types.ts

@@ -18,7 +18,7 @@ export type { TagLibModule } from "./wasm.ts";
  *
  * @example
  * ```typescript
- * const file = await taglib.openFile(buffer);
+ * const file = await taglib.open(buffer);
  * const format = file.getFormat();
  * if (format === "MP3") {
  *   // Handle MP3-specific features

package/src/utils/file.ts

@@ -0,0 +1,82 @@
+/**
+ * File reading utilities for taglib-wasm
+ * Provides cross-runtime support for reading files from various sources
+ */
+
+import { EnvironmentError, FileOperationError } from "../errors.ts";
+
+/**
+ * Read a file's data from various sources.
+ * Supports file paths (Node.js/Deno/Bun), buffers, and File objects (browser).
+ *
+ * @param file - File path, Uint8Array, ArrayBuffer, or File object
+ * @returns Promise resolving to Uint8Array of file data
+ * @throws {FileOperationError} If file read fails
+ * @throws {EnvironmentError} If environment doesn't support file paths
+ */
+export async function readFileData(
+  file: string | Uint8Array | ArrayBuffer | File,
+): Promise<Uint8Array> {
+  // Already a Uint8Array
+  if (file instanceof Uint8Array) {
+    return file;
+  }
+
+  // ArrayBuffer - convert to Uint8Array
+  if (file instanceof ArrayBuffer) {
+    return new Uint8Array(file);
+  }
+
+  // File object (browser)
+  if (typeof File !== "undefined" && file instanceof File) {
+    return new Uint8Array(await file.arrayBuffer());
+  }
+
+  // String path - read from filesystem
+  if (typeof file === "string") {
+    try {
+      // Deno
+      if (typeof Deno !== "undefined") {
+        return await Deno.readFile(file);
+      }
+
+      // Node.js
+      if (
+        typeof process !== "undefined" && process.versions &&
+        process.versions.node
+      ) {
+        const { readFile } = await import("fs/promises");
+        return new Uint8Array(await readFile(file));
+      }
+
+      // Bun
+      if (typeof (globalThis as any).Bun !== "undefined") {
+        const bunFile = (globalThis as any).Bun.file(file);
+        return new Uint8Array(await bunFile.arrayBuffer());
+      }
+    } catch (error) {
+      // Convert system file errors to FileOperationError
+      throw new FileOperationError(
+        "read",
+        (error as Error).message,
+        file
+      );
+    }
+
+    const env = typeof Deno !== "undefined" ? "Deno" :
+                typeof process !== "undefined" ? "Node.js" :
+                typeof (globalThis as any).Bun !== "undefined" ? "Bun" :
+                "Browser";
+    throw new EnvironmentError(
+      env,
+      "does not support file path reading",
+      "filesystem access"
+    );
+  }
+
+  const inputType = Object.prototype.toString.call(file);
+  throw new FileOperationError(
+    "read",
+    `Invalid file input type: ${inputType}. Expected string path, Uint8Array, ArrayBuffer, or File object.`
+  );
+}

package/src/utils/write.ts

@@ -0,0 +1,61 @@
+/**
+ * File writing utilities for taglib-wasm
+ * Provides cross-runtime support for writing files
+ */
+
+import { EnvironmentError, FileOperationError } from "../errors.ts";
+
+/**
+ * Write data to a file across different runtimes.
+ * Supports Node.js, Deno, and Bun environments.
+ *
+ * @param path - File path to write to
+ * @param data - Data to write (Uint8Array)
+ * @throws {FileOperationError} If file write fails
+ * @throws {EnvironmentError} If environment doesn't support file writing
+ */
+export async function writeFileData(
+  path: string,
+  data: Uint8Array,
+): Promise<void> {
+  try {
+    // Deno
+    if (typeof Deno !== "undefined") {
+      await Deno.writeFile(path, data);
+      return;
+    }
+
+    // Node.js
+    if (
+      typeof process !== "undefined" && process.versions &&
+      process.versions.node
+    ) {
+      const { writeFile } = await import("fs/promises");
+      await writeFile(path, data);
+      return;
+    }
+
+    // Bun
+    if (typeof (globalThis as any).Bun !== "undefined") {
+      await (globalThis as any).Bun.write(path, data);
+      return;
+    }
+  } catch (error) {
+    // Convert system file errors to FileOperationError
+    throw new FileOperationError(
+      "write",
+      (error as Error).message,
+      path
+    );
+  }
+
+  const env = typeof Deno !== "undefined" ? "Deno" :
+              typeof process !== "undefined" ? "Node.js" :
+              typeof (globalThis as any).Bun !== "undefined" ? "Bun" :
+              "Browser";
+  throw new EnvironmentError(
+    env,
+    "does not support file path writing",
+    "filesystem access"
+  );
+}

package/src/wasm-workers.ts

@@ -3,6 +3,7 @@
  */
 
 import type { TagLibConfig, TagLibModule } from "./types.ts";
+import { TagLibInitializationError } from "./errors.ts";
 
 // Re-export TagLibModule for convenience
 export type { TagLibModule };
@@ -69,7 +70,10 @@ export async function loadTagLibModuleForWorkers(
     const TagLibWasm = await createWorkersCompatibleModule();
 
     if (typeof TagLibWasm !== "function") {
-      throw new Error("Failed to load taglib-wasm module for Workers");
+      throw new TagLibInitializationError(
+        "Failed to load taglib-wasm module for Workers. " +
+          "The module may not be properly bundled for the Workers environment.",
+      );
     }
 
     const wasmInstance = await TagLibWasm(moduleConfig);
@@ -91,8 +95,12 @@ export async function loadTagLibModuleForWorkers(
 
     return wasmInstance as TagLibModule;
   } catch (error) {
-    throw new Error(
+    if (error instanceof TagLibInitializationError) {
+      throw error;
+    }
+    throw new TagLibInitializationError(
       `Failed to load taglib-wasm for Workers: ${(error as Error).message}`,
+      { error: (error as Error).message },
     );
   }
 }
@@ -110,14 +118,15 @@ async function createWorkersCompatibleModule(): Promise<any> {
   // For now, we'll attempt to load the existing module with Workers compatibility
   try {
     // Try to import the existing module
-    const wasmModule = await import("../build/taglib.js");
+    const wasmModule = await import("../build/taglib-wrapper.js");
     return wasmModule.default || wasmModule;
   } catch (error) {
     // If that fails, provide a fallback implementation
-    throw new Error(
+    throw new TagLibInitializationError(
       "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}`,
+      { error: (error as Error).message },
     );
   }
 }

package/src/wasm.ts

@@ -84,7 +84,7 @@ export interface AudioPropertiesWrapper {
   channels(): number;
 }
 
-export interface TagLibModule extends EmscriptenModule {
+export interface TagLibModule extends Omit<EmscriptenModule, 'then'> {
   // Embind classes
   FileHandle: new () => FileHandle;
   TagWrapper: new () => TagWrapper;

package/src/web-utils.ts

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview Web browser utilities for working with cover art in taglib-wasm
+ *
+ * This module provides browser-specific helpers for integrating taglib-wasm
+ * with web applications, including canvas integration and data URL support.
+ *
+ * @example
+ * ```typescript
+ * import { pictureToDataURL, setCoverArtFromCanvas } from "taglib-wasm/web-utils";
+ *
+ * // Display cover art in an <img> element
+ * const pictures = await readPictures("song.mp3");
+ * if (pictures.length > 0) {
+ *   const dataURL = pictureToDataURL(pictures[0]);
+ *   document.getElementById('cover').src = dataURL;
+ * }
+ *
+ * // Set cover art from a canvas
+ * const canvas = document.getElementById('myCanvas') as HTMLCanvasElement;
+ * const modifiedBuffer = await setCoverArtFromCanvas("song.mp3", canvas);
+ * ```
+ */
+
+import type { Picture } from "./types.ts";
+import { PictureType } from "./types.ts";
+import { applyPictures, readPictures } from "./simple.ts";
+
+/**
+ * Convert a Picture object to a data URL for display in web browsers
+ *
+ * @param picture - Picture object from taglib-wasm
+ * @returns Data URL string that can be used as src for <img> elements
+ *
+ * @example
+ * ```typescript
+ * const pictures = await readPictures("song.mp3");
+ * const imgElement = document.getElementById('coverArt') as HTMLImageElement;
+ * imgElement.src = pictureToDataURL(pictures[0]);
+ * ```
+ */
+export function pictureToDataURL(picture: Picture): string {
+  // Convert Uint8Array to base64
+  const base64 = btoa(String.fromCharCode(...picture.data));
+  return `data:${picture.mimeType};base64,${base64}`;
+}
+
+/**
+ * Convert a data URL to a Picture object
+ *
+ * @param dataURL - Data URL string (e.g., "data:image/jpeg;base64,...")
+ * @param type - Picture type (defaults to FrontCover)
+ * @param description - Optional description
+ * @returns Picture object
+ *
+ * @example
+ * ```typescript
+ * const dataURL = canvas.toDataURL('image/jpeg');
+ * const picture = dataURLToPicture(dataURL, PictureType.FrontCover);
+ * const modifiedBuffer = await applyPictures("song.mp3", [picture]);
+ * ```
+ */
+export function dataURLToPicture(
+  dataURL: string,
+  type: PictureType = PictureType.FrontCover,
+  description?: string,
+): Picture {
+  // Parse data URL
+  const matches = dataURL.match(/^data:([^;]+);base64,(.+)$/);
+  if (!matches) {
+    throw new Error("Invalid data URL format");
+  }
+
+  const [, mimeType, base64] = matches;
+  
+  // Convert base64 to Uint8Array
+  const binaryString = atob(base64);
+  const data = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    data[i] = binaryString.charCodeAt(i);
+  }
+
+  return {
+    mimeType,
+    data,
+    type,
+    description,
+  };
+}
+
+/**
+ * Set cover art from an HTML canvas element
+ *
+ * @param file - File path, Uint8Array buffer, ArrayBuffer, or File object
+ * @param canvas - HTMLCanvasElement containing the image
+ * @param options - Options for image format and quality
+ * @returns Modified file buffer with cover art from canvas
+ *
+ * @example
+ * ```typescript
+ * const canvas = document.getElementById('albumArt') as HTMLCanvasElement;
+ * const modifiedBuffer = await setCoverArtFromCanvas("song.mp3", canvas, {
+ *   format: 'image/jpeg',
+ *   quality: 0.9
+ * });
+ * ```
+ */
+export async function setCoverArtFromCanvas(
+  file: string | Uint8Array | ArrayBuffer | File,
+  canvas: HTMLCanvasElement,
+  options: {
+    format?: 'image/jpeg' | 'image/png' | 'image/webp';
+    quality?: number;
+    type?: PictureType;
+    description?: string;
+  } = {},
+): Promise<Uint8Array> {
+  const {
+    format = 'image/jpeg',
+    quality = 0.92,
+    type = PictureType.FrontCover,
+    description = "Front Cover",
+  } = options;
+
+  // Convert canvas to data URL
+  const dataURL = canvas.toDataURL(format, quality);
+  
+  // Convert to Picture object
+  const picture = dataURLToPicture(dataURL, type, description);
+  
+  // Apply to file
+  return applyPictures(file, [picture]);
+}
+
+/**
+ * Convert canvas to Picture object using blob for better performance
+ *
+ * This is more efficient than toDataURL for large images as it avoids
+ * the base64 encoding/decoding step.
+ *
+ * @param canvas - HTMLCanvasElement containing the image
+ * @param options - Options for image format and quality
+ * @returns Promise resolving to Picture object
+ *
+ * @example
+ * ```typescript
+ * const canvas = document.getElementById('albumArt') as HTMLCanvasElement;
+ * const picture = await canvasToPicture(canvas, {
+ *   format: 'image/png',
+ *   type: PictureType.BackCover
+ * });
+ * ```
+ */
+export async function canvasToPicture(
+  canvas: HTMLCanvasElement,
+  options: {
+    format?: 'image/jpeg' | 'image/png' | 'image/webp';
+    quality?: number;
+    type?: PictureType;
+    description?: string;
+  } = {},
+): Promise<Picture> {
+  const {
+    format = 'image/jpeg',
+    quality = 0.92,
+    type = PictureType.FrontCover,
+    description,
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      async (blob) => {
+        if (!blob) {
+          reject(new Error("Failed to convert canvas to blob"));
+          return;
+        }
+
+        // Convert blob to Uint8Array
+        const arrayBuffer = await blob.arrayBuffer();
+        const data = new Uint8Array(arrayBuffer);
+
+        resolve({
+          mimeType: format,
+          data,
+          type,
+          description,
+        });
+      },
+      format,
+      quality,
+    );
+  });
+}
+
+/**
+ * Load an image file into a Picture object
+ *
+ * @param file - File object from <input type="file"> or drag-and-drop
+ * @param type - Picture type (defaults to FrontCover)
+ * @param description - Optional description
+ * @returns Promise resolving to Picture object
+ *
+ * @example
+ * ```typescript
+ * // From file input
+ * const input = document.getElementById('fileInput') as HTMLInputElement;
+ * input.addEventListener('change', async (e) => {
+ *   const file = e.target.files[0];
+ *   const picture = await imageFileToPicture(file);
+ *   const modifiedBuffer = await applyPictures("song.mp3", [picture]);
+ * });
+ * ```
+ */
+export async function imageFileToPicture(
+  file: File,
+  type: PictureType = PictureType.FrontCover,
+  description?: string,
+): Promise<Picture> {
+  const arrayBuffer = await file.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+  
+  return {
+    mimeType: file.type,
+    data,
+    type,
+    description: description || file.name,
+  };
+}
+
+/**
+ * Display a Picture in an HTML img element
+ *
+ * @param picture - Picture object from taglib-wasm
+ * @param imgElement - HTMLImageElement to display the picture in
+ *
+ * @example
+ * ```typescript
+ * const pictures = await readPictures("song.mp3");
+ * const img = document.getElementById('coverArt') as HTMLImageElement;
+ * displayPicture(pictures[0], img);
+ * ```
+ */
+export function displayPicture(
+  picture: Picture,
+  imgElement: HTMLImageElement,
+): void {
+  // Clean up previous object URL if any
+  if (imgElement.src.startsWith('blob:')) {
+    URL.revokeObjectURL(imgElement.src);
+  }
+
+  // Create blob and object URL
+  const blob = new Blob([picture.data], { type: picture.mimeType });
+  const objectURL = URL.createObjectURL(blob);
+  
+  // Set the src
+  imgElement.src = objectURL;
+  
+  // Clean up object URL when image is no longer needed
+  imgElement.addEventListener('load', () => {
+    // Keep the URL alive for a bit to ensure image is rendered
+    setTimeout(() => URL.revokeObjectURL(objectURL), 100);
+  }, { once: true });
+}
+
+/**
+ * Create a download link for a Picture
+ *
+ * @param picture - Picture object to download
+ * @param filename - Suggested filename for download
+ * @returns Temporary download URL (remember to revoke it after use)
+ *
+ * @example
+ * ```typescript
+ * const pictures = await readPictures("song.mp3");
+ * const downloadUrl = createPictureDownloadURL(pictures[0], "cover.jpg");
+ * 
+ * const link = document.createElement('a');
+ * link.href = downloadUrl;
+ * link.download = "cover.jpg";
+ * link.click();
+ * 
+ * // Clean up
+ * URL.revokeObjectURL(downloadUrl);
+ * ```
+ */
+export function createPictureDownloadURL(
+  picture: Picture,
+  filename: string = "cover",
+): string {
+  const blob = new Blob([picture.data], { type: picture.mimeType });
+  return URL.createObjectURL(blob);
+}
+
+/**
+ * Extract all pictures and create a gallery
+ *
+ * @param file - Audio file to extract pictures from
+ * @param container - HTML element to append gallery items to
+ * @param options - Gallery display options
+ *
+ * @example
+ * ```typescript
+ * const galleryDiv = document.getElementById('pictureGallery');
+ * await createPictureGallery("song.mp3", galleryDiv, {
+ *   className: 'album-art',
+ *   includeDescription: true
+ * });
+ * ```
+ */
+export async function createPictureGallery(
+  file: string | Uint8Array | ArrayBuffer | File,
+  container: HTMLElement,
+  options: {
+    className?: string;
+    includeDescription?: boolean;
+    onClick?: (picture: Picture, index: number) => void;
+  } = {},
+): Promise<void> {
+  const pictures = await readPictures(file);
+  
+  // Clear container
+  container.innerHTML = '';
+  
+  pictures.forEach((picture, index) => {
+    const wrapper = document.createElement('div');
+    wrapper.className = options.className || 'picture-item';
+    
+    const img = document.createElement('img');
+    displayPicture(picture, img);
+    img.alt = picture.description || `Picture ${index + 1}`;
+    
+    if (options.onClick) {
+      img.style.cursor = 'pointer';
+      img.addEventListener('click', () => options.onClick!(picture, index));
+    }
+    
+    wrapper.appendChild(img);
+    
+    if (options.includeDescription && picture.description) {
+      const caption = document.createElement('p');
+      caption.textContent = picture.description;
+      wrapper.appendChild(caption);
+    }
+    
+    container.appendChild(wrapper);
+  });
+}

package/src/workers.ts

@@ -21,6 +21,11 @@ import {
   loadTagLibModuleForWorkers,
   type TagLibModule,
 } from "./wasm-workers.ts";
+import {
+  EnvironmentError,
+  InvalidFormatError,
+  MemoryError,
+} from "./errors.ts";
 
 /**
  * Represents an audio file with metadata and properties (Workers-compatible).
@@ -123,7 +128,6 @@ export class AudioFileWorkers {
       bitrate,
       sampleRate,
       channels,
-      format: this.format(),
     };
   }
 
@@ -324,7 +328,7 @@ export class TagLibWorkers {
    * import wasmBinary from "../build/taglib.wasm";
    *
    * const taglib = await TagLibWorkers.initialize(wasmBinary);
-   * const file = taglib.openFile(audioBuffer);
+   * const file = taglib.open(audioBuffer);
    * const metadata = file.tag();
    * ```
    */
@@ -348,12 +352,15 @@ export class TagLibWorkers {
    * @example
    * ```typescript
    * const audioData = new Uint8Array(await request.arrayBuffer());
-   * const file = taglib.openFile(audioData);
+   * const file = taglib.open(audioData);
    * ```
    */
-  openFile(buffer: Uint8Array): AudioFileWorkers {
+  open(buffer: Uint8Array): AudioFileWorkers {
     if (!this.module.HEAPU8) {
-      throw new Error("Wasm module not properly initialized - missing HEAPU8");
+      throw new MemoryError(
+        "Wasm module not properly initialized: missing HEAPU8. " +
+          "The module may not have loaded correctly in the Workers environment."
+      );
     }
 
     // Use Emscripten's allocate function for proper memory management
@@ -366,8 +373,10 @@ export class TagLibWorkers {
     }
 
     if (!this.module._taglib_file_new_from_buffer) {
-      throw new Error(
-        "Workers API requires C-style functions. Use Core API instead.",
+      throw new EnvironmentError(
+        "Workers",
+        "requires C-style functions which are not available. Use the Core API instead for this environment",
+        "C-style function exports"
       );
     }
 
@@ -377,11 +386,11 @@ export class TagLibWorkers {
     );
 
     if (fileId === 0) {
-      console.log(
-        `DEBUG: File creation failed, not freeing memory at ${dataPtr}`,
-      );
-      throw new Error(
-        "Failed to open audio file - invalid format or corrupted data",
+      // Free the allocated memory since file creation failed
+      this.module._free(dataPtr);
+      throw new InvalidFormatError(
+        "Failed to open audio file. File format may be invalid or not supported",
+        buffer.length
       );
     }
 
@@ -391,6 +400,16 @@ export class TagLibWorkers {
     return new AudioFileWorkers(this.module, fileId);
   }
 
+  /**
+   * @deprecated Use `open()` instead. This method will be removed in the next major version.
+   * Open an audio file from a buffer (backward compatibility).
+   * @param buffer Audio file data as Uint8Array
+   * @returns Audio file instance
+   */
+  openFile(buffer: Uint8Array): AudioFileWorkers {
+    return this.open(buffer);
+  }
+
   /**
    * Get the underlying Wasm module for advanced usage.
    * @returns The initialized TagLib Wasm module
@@ -425,7 +444,7 @@ export async function processAudioMetadata(
   { tag: Tag; properties: AudioProperties | null; format: AudioFormat }
 > {
   const taglib = await TagLibWorkers.initialize(wasmBinary, config);
-  const file = taglib.openFile(audioData);
+  const file = taglib.open(audioData);
 
   try {
     const tag = file.tag();