taglib-wasm 0.3.13 → 0.3.15

package/dist/src/workers.ts

@@ -1,461 +0,0 @@
-/**
- * @fileoverview Cloudflare Workers-specific TagLib API
- *
- * This module provides a specialized API for using TagLib in Cloudflare Workers
- * and other edge computing environments where the standard Emscripten module
- * loading may not work. It uses C-style function exports for compatibility.
- *
- * @module taglib-wasm/workers
- */
-
-import type {
-  AudioFormat,
-  AudioProperties,
-  ExtendedTag,
-  Tag,
-  TagLibConfig,
-} from "./types.ts";
-import {
-  cStringToJS,
-  jsToCString,
-  loadTagLibModuleForWorkers,
-  type TagLibModule,
-} from "./wasm-workers.ts";
-import { EnvironmentError, InvalidFormatError, MemoryError } from "./errors.ts";
-
-/**
- * Represents an audio file with metadata and properties (Workers-compatible).
- * This implementation uses C-style function calls for Cloudflare Workers compatibility.
- *
- * @example
- * ```typescript
- * const file = taglib.openFile(audioBuffer);
- *
- * // Get metadata
- * const tag = file.tag();
- * console.log(tag.title);
- *
- * // Modify metadata
- * file.setTitle("New Title");
- * file.save();
- *
- * // Clean up
- * file.dispose();
- * ```
- */
-export class AudioFileWorkers {
-  private module: TagLibModule;
-  private fileId: number;
-  private tagPtr: number;
-  private propsPtr: number;
-
-  constructor(module: TagLibModule, fileId: number) {
-    this.module = module;
-    this.fileId = fileId;
-    this.tagPtr = module._taglib_file_tag?.(fileId) || 0;
-    this.propsPtr = module._taglib_file_audioproperties?.(fileId) || 0;
-  }
-
-  /**
-   * Check if the file is valid and was loaded successfully.
-   * @returns true if the file is valid and can be processed
-   */
-  isValid(): boolean {
-    return this.module._taglib_file_is_valid?.(this.fileId) !== 0;
-  }
-
-  /**
-   * Get the file format.
-   * @returns Audio format (e.g., "MP3", "FLAC", "OGG")
-   */
-  format(): AudioFormat {
-    const formatPtr = this.module._taglib_file_format?.(this.fileId) || 0;
-    if (formatPtr === 0) return "MP3"; // fallback
-    const formatStr = cStringToJS(this.module, formatPtr);
-    return formatStr as AudioFormat;
-  }
-
-  /**
-   * Get basic tag information.
-   * @returns Object containing title, artist, album, etc.
-   */
-  tag(): Tag {
-    if (this.tagPtr === 0) return {};
-
-    const title = this.module._taglib_tag_title?.(this.tagPtr) || 0;
-    const artist = this.module._taglib_tag_artist?.(this.tagPtr) || 0;
-    const album = this.module._taglib_tag_album?.(this.tagPtr) || 0;
-    const comment = this.module._taglib_tag_comment?.(this.tagPtr) || 0;
-    const genre = this.module._taglib_tag_genre?.(this.tagPtr) || 0;
-    const year = this.module._taglib_tag_year?.(this.tagPtr) || 0;
-    const track = this.module._taglib_tag_track?.(this.tagPtr) || 0;
-
-    return {
-      title: title ? cStringToJS(this.module, title) : undefined,
-      artist: artist ? cStringToJS(this.module, artist) : undefined,
-      album: album ? cStringToJS(this.module, album) : undefined,
-      comment: comment ? cStringToJS(this.module, comment) : undefined,
-      genre: genre ? cStringToJS(this.module, genre) : undefined,
-      year: year || undefined,
-      track: track || undefined,
-    };
-  }
-
-  /**
-   * Get audio properties (duration, bitrate, etc.).
-   * @returns Audio properties or null if unavailable
-   */
-  audioProperties(): AudioProperties | null {
-    if (this.propsPtr === 0) return null;
-
-    const length =
-      this.module._taglib_audioproperties_length?.(this.propsPtr) || 0;
-    const bitrate =
-      this.module._taglib_audioproperties_bitrate?.(this.propsPtr) || 0;
-    const sampleRate = this.module._taglib_audioproperties_samplerate?.(
-      this.propsPtr,
-    ) || 0;
-    const channels = this.module._taglib_audioproperties_channels?.(
-      this.propsPtr,
-    ) || 0;
-
-    return {
-      length,
-      bitrate,
-      sampleRate,
-      channels,
-    };
-  }
-
-  /**
-   * Set the title tag.
-   * @param title - New title value
-   */
-  setTitle(title: string): void {
-    if (this.tagPtr === 0) return;
-    const titlePtr = jsToCString(this.module, title);
-    this.module._taglib_tag_set_title?.(this.tagPtr, titlePtr);
-    this.module._free(titlePtr);
-  }
-
-  /**
-   * Set the artist tag.
-   * @param artist - New artist value
-   */
-  setArtist(artist: string): void {
-    if (this.tagPtr === 0) return;
-    const artistPtr = jsToCString(this.module, artist);
-    this.module._taglib_tag_set_artist?.(this.tagPtr, artistPtr);
-    this.module._free(artistPtr);
-  }
-
-  /**
-   * Set the album tag.
-   * @param album - New album value
-   */
-  setAlbum(album: string): void {
-    if (this.tagPtr === 0) return;
-    const albumPtr = jsToCString(this.module, album);
-    this.module._taglib_tag_set_album?.(this.tagPtr, albumPtr);
-    this.module._free(albumPtr);
-  }
-
-  /**
-   * Set the comment tag.
-   * @param comment - New comment value
-   */
-  setComment(comment: string): void {
-    if (this.tagPtr === 0) return;
-    const commentPtr = jsToCString(this.module, comment);
-    this.module._taglib_tag_set_comment?.(this.tagPtr, commentPtr);
-    this.module._free(commentPtr);
-  }
-
-  /**
-   * Set the genre tag.
-   * @param genre - New genre value
-   */
-  setGenre(genre: string): void {
-    if (this.tagPtr === 0) return;
-    const genrePtr = jsToCString(this.module, genre);
-    this.module._taglib_tag_set_genre?.(this.tagPtr, genrePtr);
-    this.module._free(genrePtr);
-  }
-
-  /**
-   * Set the year tag.
-   * @param year - Release year
-   */
-  setYear(year: number): void {
-    if (this.tagPtr === 0) return;
-    this.module._taglib_tag_set_year?.(this.tagPtr, year);
-  }
-
-  /**
-   * Set the track number tag.
-   * @param track - Track number
-   */
-  setTrack(track: number): void {
-    if (this.tagPtr === 0) return;
-    this.module._taglib_tag_set_track?.(this.tagPtr, track);
-  }
-
-  /**
-   * Save changes to the file.
-   * Note: In Workers context, this saves to the in-memory buffer only.
-   * @returns true if save was successful
-   */
-  save(): boolean {
-    if (this.fileId !== 0) {
-      return this.module._taglib_file_save?.(this.fileId) !== 0;
-    }
-    return false;
-  }
-
-  /**
-   * Get the current file buffer after modifications.
-   * Note: This is not implemented in the Workers API.
-   * @returns Empty Uint8Array (not implemented)
-   * @deprecated Use the Core API for this functionality
-   */
-  getFileBuffer(): Uint8Array {
-    console.warn(
-      "getFileBuffer() is not implemented in Workers API. Use Core API for this functionality.",
-    );
-    return new Uint8Array(0);
-  }
-
-  /**
-   * Get extended metadata with format-agnostic field names.
-   * Note: Currently returns only basic fields in Workers API.
-   * @returns Extended tag object with basic fields populated
-   */
-  extendedTag(): ExtendedTag {
-    const basicTag = this.tag();
-
-    return {
-      ...basicTag,
-      // Advanced fields placeholder - would be populated by PropertyMap reading
-      acoustidFingerprint: undefined,
-      acoustidId: undefined,
-      musicbrainzTrackId: undefined,
-      musicbrainzReleaseId: undefined,
-      musicbrainzArtistId: undefined,
-      musicbrainzReleaseGroupId: undefined,
-      albumArtist: undefined,
-      composer: undefined,
-      discNumber: undefined,
-      totalTracks: undefined,
-      totalDiscs: undefined,
-      bpm: undefined,
-      compilation: undefined,
-      titleSort: undefined,
-      artistSort: undefined,
-      albumSort: undefined,
-      replayGainTrackGain: undefined,
-      replayGainTrackPeak: undefined,
-      replayGainAlbumGain: undefined,
-      replayGainAlbumPeak: undefined,
-      appleSoundCheck: undefined,
-    };
-  }
-
-  /**
-   * Set extended metadata using format-agnostic field names.
-   * Note: Currently only supports basic fields in Workers API.
-   * @param tag - Partial extended tag object with fields to update
-   */
-  setExtendedTag(tag: Partial<ExtendedTag>): void {
-    if (tag.title !== undefined) this.setTitle(tag.title);
-    if (tag.artist !== undefined) this.setArtist(tag.artist);
-    if (tag.album !== undefined) this.setAlbum(tag.album);
-    if (tag.comment !== undefined) this.setComment(tag.comment);
-    if (tag.genre !== undefined) this.setGenre(tag.genre);
-    if (tag.year !== undefined) this.setYear(tag.year);
-    if (tag.track !== undefined) this.setTrack(tag.track);
-  }
-
-  /**
-   * Clean up resources.
-   * Always call this when done to prevent memory leaks.
-   */
-  dispose(): void {
-    if (this.fileId !== 0) {
-      this.module._taglib_file_delete?.(this.fileId);
-      this.fileId = 0;
-    }
-  }
-}
-
-/**
- * Main TagLib class for Cloudflare Workers.
- * Provides methods to initialize the library and open audio files
- * in edge computing environments.
- *
- * @example
- * ```typescript
- * import wasmBinary from "../build/taglib.wasm";
- *
- * // Initialize TagLib
- * const taglib = await TagLibWorkers.initialize(wasmBinary);
- *
- * // Process audio file
- * const file = taglib.openFile(audioBuffer);
- * const metadata = file.tag();
- * file.dispose();
- * ```
- */
-export class TagLibWorkers {
-  private module: TagLibModule;
-
-  private constructor(module: TagLibModule) {
-    this.module = module;
-  }
-
-  /**
-   * Initialize TagLib for Workers with Wasm binary
-   *
-   * @param wasmBinary - The WebAssembly binary as Uint8Array
-   * @param config - Optional configuration for the Wasm module
-   *
-   * @example
-   * ```typescript
-   * // In a Cloudflare Worker
-   * import wasmBinary from "../build/taglib.wasm";
-   *
-   * const taglib = await TagLibWorkers.initialize(wasmBinary);
-   * const file = taglib.open(audioBuffer);
-   * const metadata = file.tag();
-   * ```
-   */
-  static async initialize(
-    wasmBinary: Uint8Array,
-    config?: TagLibConfig,
-  ): Promise<TagLibWorkers> {
-    const module = await loadTagLibModuleForWorkers(wasmBinary, config);
-    return new TagLibWorkers(module);
-  }
-
-  /**
-   * Open an audio file from a buffer.
-   *
-   * @param buffer - Audio file data as Uint8Array
-   * @returns AudioFileWorkers instance
-   * @throws {Error} If Wasm module is not initialized
-   * @throws {Error} If file format is invalid or unsupported
-   * @throws {Error} If Workers API C-style functions are not available
-   *
-   * @example
-   * ```typescript
-   * const audioData = new Uint8Array(await request.arrayBuffer());
-   * const file = taglib.open(audioData);
-   * ```
-   */
-  open(buffer: Uint8Array): AudioFileWorkers {
-    if (!this.module.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
-    let dataPtr: number;
-    if (this.module.allocate && this.module.ALLOC_NORMAL !== undefined) {
-      dataPtr = this.module.allocate(buffer, this.module.ALLOC_NORMAL);
-    } else {
-      dataPtr = this.module._malloc(buffer.length);
-      this.module.HEAPU8.set(buffer, dataPtr);
-    }
-
-    if (!this.module._taglib_file_new_from_buffer) {
-      throw new EnvironmentError(
-        "Workers",
-        "requires C-style functions which are not available. Use the Core API instead for this environment",
-        "C-style function exports",
-      );
-    }
-
-    const fileId = this.module._taglib_file_new_from_buffer(
-      dataPtr,
-      buffer.length,
-    );
-
-    if (fileId === 0) {
-      // 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,
-      );
-    }
-
-    // Free the temporary buffer copy (TagLib has made its own copy in ByteVector)
-    this.module._free(dataPtr);
-
-    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
-   */
-  getModule(): TagLibModule {
-    return this.module;
-  }
-}
-
-/**
- * Utility function to process audio metadata in a Cloudflare Worker
- *
- * @example
- * ```typescript
- * export default {
- *   async fetch(request: Request): Promise<Response> {
- *     if (request.method === "POST") {
- *       const audioData = new Uint8Array(await request.arrayBuffer());
- *       const metadata = await processAudioMetadata(wasmBinary, audioData);
- *       return Response.json(metadata);
- *     }
- *     return new Response("Method not allowed", { status: 405 });
- *   }
- * };
- * ```
- */
-export async function processAudioMetadata(
-  wasmBinary: Uint8Array,
-  audioData: Uint8Array,
-  config?: TagLibConfig,
-): Promise<
-  { tag: Tag; properties: AudioProperties | null; format: AudioFormat }
-> {
-  const taglib = await TagLibWorkers.initialize(wasmBinary, config);
-  const file = taglib.open(audioData);
-
-  try {
-    const tag = file.tag();
-    const properties = file.audioProperties();
-    const format = file.format();
-
-    return { tag, properties, format };
-  } finally {
-    file.dispose();
-  }
-}
-
-/**
- * Re-export commonly used types for convenience.
- * These types define the structure of metadata, audio properties,
- * and configuration options.
- */
-export type { AudioFormat, AudioProperties, ExtendedTag, Tag, TagLibConfig };

package/dist/src/write.js

@@ -1,33 +0,0 @@
-import { EnvironmentError, FileOperationError } from "../errors.ts";
-async function writeFileData(path, data) {
-  try {
-    if (typeof globalThis.Deno !== "undefined") {
-      await globalThis.Deno.writeFile(path, data);
-      return;
-    }
-    if (typeof globalThis.process !== "undefined" && globalThis.process.versions && globalThis.process.versions.node) {
-      const { writeFile } = await import("fs/promises");
-      await writeFile(path, data);
-      return;
-    }
-    if (typeof globalThis.Bun !== "undefined") {
-      await globalThis.Bun.write(path, data);
-      return;
-    }
-  } catch (error) {
-    throw new FileOperationError(
-      "write",
-      error.message,
-      path
-    );
-  }
-  const env = typeof globalThis.Deno !== "undefined" ? "Deno" : typeof globalThis.process !== "undefined" ? "Node.js" : typeof globalThis.Bun !== "undefined" ? "Bun" : "Browser";
-  throw new EnvironmentError(
-    env,
-    "does not support file path writing",
-    "filesystem access"
-  );
-}
-export {
-  writeFileData
-};

package/index.ts

@@ -1,221 +0,0 @@
-/**
- * @fileoverview Main module exports for taglib-wasm
- *
- * TagLib v2.1 compiled to WebAssembly with TypeScript bindings
- * for universal audio metadata handling across all JavaScript runtimes.
- *
- * @module taglib-wasm
- *
- * @example
- * ```typescript
- * // Using the Core API
- * import { TagLib } from "taglib-wasm";
- *
- * const taglib = await TagLib.initialize();
- * const file = await taglib.open(audioBuffer);
- * const tag = file.tag();
- * console.log(tag.title);
- * file.dispose();
- * ```
- *
- * @example
- * ```typescript
- * // Using the Simple API
- * import { readTags, applyTags } from "taglib-wasm/simple";
- *
- * const tags = await readTags("song.mp3");
- * console.log(tags.artist);
- *
- * const modified = await applyTags("song.mp3", {
- *   artist: "New Artist",
- *   album: "New Album"
- * });
- * ```
- */
-
-/**
- * Core API exports for advanced usage with full control.
- * @see {@link TagLib} - Main TagLib class
- * @see {@link AudioFile} - Audio file interface
- * @see {@link createTagLib} - Factory function for creating TagLib instances
- */
-export {
-  AudioFileImpl as AudioFile,
-  createTagLib,
-  TagLib,
-} from "./src/taglib.ts";
-
-/**
- * Error types for proper error handling and debugging.
- * @see {@link TagLibError} - Base error class for all TagLib errors
- * @see {@link TagLibInitializationError} - Wasm initialization failures
- * @see {@link InvalidFormatError} - Invalid or corrupted file format
- * @see {@link UnsupportedFormatError} - Valid but unsupported format
- * @see {@link FileOperationError} - File read/write/save failures
- * @see {@link MetadataError} - Tag reading/writing failures
- * @see {@link MemoryError} - Wasm memory allocation issues
- * @see {@link EnvironmentError} - Runtime/environment issues
- */
-export {
-  EnvironmentError,
-  FileOperationError,
-  InvalidFormatError,
-  isEnvironmentError,
-  isFileOperationError,
-  isInvalidFormatError,
-  isMemoryError,
-  isMetadataError,
-  isTagLibError,
-  isUnsupportedFormatError,
-  MemoryError,
-  MetadataError,
-  SUPPORTED_FORMATS,
-  TagLibError,
-  TagLibInitializationError,
-  UnsupportedFormatError,
-} from "./src/errors.ts";
-
-/**
- * Simple API exports for easy tag reading and writing.
- * @see {@link readTags} - Read metadata from audio files
- * @see {@link applyTags} - Apply metadata changes and return modified buffer
- * @see {@link updateTags} - Update metadata and save to disk
- * @see {@link writeTags} - Deprecated alias for applyTags
- * @see {@link readProperties} - Read audio properties
- * @see {@link readPictures} - Read cover art/pictures
- * @see {@link applyPictures} - Apply pictures to audio files
- * @see {@link getCoverArt} - Get primary cover art data
- * @see {@link setCoverArt} - Set primary cover art
- */
-export {
-  addPicture,
-  applyPictures,
-  applyTags,
-  clearPictures,
-  clearTags,
-  findPictureByType,
-  getCoverArt,
-  getFormat,
-  getPictureMetadata,
-  isValidAudioFile,
-  readPictures,
-  readProperties,
-  readTags,
-  replacePictureByType,
-  setCoverArt,
-  updateTags
-} from "./src/simple.ts";
-
-/**
- * Constants and utilities for tag name validation.
- * @see {@link Tags} - Standard tag name constants
- * @see {@link FormatMappings} - Format-specific field mappings
- * @see {@link isValidTagName} - Validate tag names
- * @see {@link getAllTagNames} - Get all valid tag names
- */
-export {
-  FormatMappings,
-  getAllTagNames,
-  isValidTagName,
-  Tags,
-} from "./src/constants.ts";
-/**
- * File I/O utilities for cover art operations.
- * @see {@link exportCoverArt} - Export cover art to file
- * @see {@link importCoverArt} - Import cover art from file
- * @see {@link copyCoverArt} - Copy cover art between files
- */
-export {
-  copyCoverArt,
-  exportAllPictures,
-  exportCoverArt,
-  exportPictureByType,
-  findCoverArtFiles,
-  importCoverArt,
-  importPictureWithType,
-  loadPictureFromFile,
-  savePictureToFile,
-} from "./src/file-utils.ts";
-
-/**
- * Web browser utilities for cover art operations.
- * @see {@link pictureToDataURL} - Convert picture to data URL
- * @see {@link setCoverArtFromCanvas} - Set cover art from HTML canvas
- * @see {@link displayPicture} - Display picture in HTML img element
- */
-export {
-  canvasToPicture,
-  createPictureDownloadURL,
-  createPictureGallery,
-  dataURLToPicture,
-  displayPicture,
-  imageFileToPicture,
-  pictureToDataURL,
-  setCoverArtFromCanvas,
-} from "./src/web-utils.ts";
-
-/**
- * Type exports for TypeScript users.
- * These types define the structure of metadata, audio properties,
- * and configuration options used throughout the library.
- *
- * @see {@link Tag} - Basic metadata structure
- * @see {@link ExtendedTag} - Extended metadata with advanced fields
- * @see {@link AudioProperties} - Audio technical properties
- * @see {@link TagLibConfig} - Configuration options
- */
-export type {
-  AudioFormat,
-  AudioProperties,
-  ExtendedTag,
-  FieldMapping,
-  FileType,
-  Picture,
-  PropertyMap,
-  Tag,
-  TagLibConfig,
-  TagName,
-} from "./src/types.ts";
-
-/**
- * Enum exports
- */
-export { PictureType } from "./src/types.ts";
-
-/**
- * Wasm module types for advanced usage.
- * @see {@link TagLibModule} - Full TagLib Wasm module interface
- * @see {@link WasmModule} - Base Emscripten module interface
- */
-export type { TagLibModule, WasmModule } from "./src/wasm.ts";
-
-// Import the type for use in this file
-import type { TagLibModule } from "./src/wasm.ts";
-
-/**
- * Load the TagLib Wasm module.
- * This function initializes the WebAssembly module and returns
- * the loaded module for use with the Core API.
- *
- * @returns Promise resolving to the initialized TagLib module
- *
- * @example
- * ```typescript
- * import { loadTagLibModule, createTagLib } from "taglib-wasm";
- *
- * // Manual module loading for advanced configuration
- * const module = await loadTagLibModule();
- * const taglib = await createTagLib(module);
- * ```
- *
- * @note Most users should use `TagLib.initialize()` instead,
- * which handles module loading automatically.
- */
-export async function loadTagLibModule(): Promise<TagLibModule> {
-  // Now that we're using ES6 modules, we can use dynamic import directly
-  const { default: createTagLibModule } = await import(
-    "./build/taglib-wrapper.js"
-  );
-  const module = await createTagLibModule();
-  return module as TagLibModule;
-}