taglib-wasm 0.1.0

package/src/enhanced-api.ts

@@ -0,0 +1,274 @@
+/**
+ * Enhanced API patterns inspired by node-taglib
+ * 
+ * This file demonstrates potential API improvements that could be added
+ * to TagLib WASM to improve developer experience.
+ */
+
+import type { AudioFile, TagLibConfig } from "./types.ts";
+
+/**
+ * Enhanced error handling with error codes
+ */
+export interface TagLibError extends Error {
+  code: 'FILE_NOT_FOUND' | 'INVALID_FORMAT' | 'MEMORY_ERROR' | 'PERMISSION_DENIED' | 'WASM_ERROR';
+  path?: string;
+  format?: string;
+  details?: string;
+}
+
+/**
+ * Callback-style async operations (Node.js pattern)
+ */
+export type TagLibCallback<T> = (err: TagLibError | null, result?: T) => void;
+
+/**
+ * Enhanced input types
+ */
+export type AudioInput = 
+  | string              // File path (Node.js/Deno/Bun only)
+  | Uint8Array         // Raw bytes
+  | ArrayBuffer        // ArrayBuffer
+  | Buffer             // Node.js Buffer
+  | File;              // Browser File object
+
+/**
+ * Enhanced TagLib class with multiple API patterns
+ */
+export class EnhancedTagLib {
+  /**
+   * Synchronous initialization (for server environments)
+   */
+  static initializeSync(config?: TagLibConfig): EnhancedTagLib {
+    // Implementation would be synchronous version
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Asynchronous initialization (current pattern)
+   */
+  static async initialize(config?: TagLibConfig): Promise<EnhancedTagLib> {
+    // Current implementation
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Open file with flexible input types
+   */
+  openFile(input: AudioInput): EnhancedAudioFile {
+    if (typeof input === 'string') {
+      return this.openFileFromPath(input);
+    } else if (input instanceof File) {
+      return this.openFileFromBrowserFile(input);
+    } else if (input instanceof ArrayBuffer) {
+      return this.openFileFromBuffer(new Uint8Array(input));
+    } else if (Buffer && Buffer.isBuffer(input)) {
+      return this.openFileFromBuffer(new Uint8Array(input));
+    } else {
+      return this.openFileFromBuffer(input);
+    }
+  }
+
+  /**
+   * Async file opening with callback pattern
+   */
+  openFileAsync(input: AudioInput, callback: TagLibCallback<EnhancedAudioFile>): void {
+    try {
+      const file = this.openFile(input);
+      callback(null, file);
+    } catch (error) {
+      const tagLibError: TagLibError = {
+        name: 'TagLibError',
+        message: error.message,
+        code: 'INVALID_FORMAT',
+        details: error.stack,
+      };
+      callback(tagLibError);
+    }
+  }
+
+  /**
+   * Sync file opening (Node.js/Bun/Deno only)
+   */
+  openFileSync(path: string): EnhancedAudioFile {
+    // Runtime-specific implementation
+    if (typeof Deno !== 'undefined') {
+      const data = Deno.readFileSync(path);
+      return this.openFileFromBuffer(data);
+    } else if (typeof Bun !== 'undefined') {
+      const file = Bun.file(path);
+      const data = new Uint8Array(file.arrayBufferSync());
+      return this.openFileFromBuffer(data);
+    } else if (typeof require !== 'undefined') {
+      const fs = require('fs');
+      const data = fs.readFileSync(path);
+      return this.openFileFromBuffer(new Uint8Array(data));
+    } else {
+      throw new Error('Synchronous file reading not supported in browser environment');
+    }
+  }
+
+  private openFileFromPath(path: string): EnhancedAudioFile {
+    throw new Error("Not implemented");
+  }
+
+  private openFileFromBrowserFile(file: File): EnhancedAudioFile {
+    throw new Error("Not implemented - requires async operation");
+  }
+
+  private openFileFromBuffer(buffer: Uint8Array): EnhancedAudioFile {
+    throw new Error("Not implemented");
+  }
+}
+
+/**
+ * Enhanced AudioFile with property accessors and better error handling
+ */
+export class EnhancedAudioFile {
+  // Property accessors (more intuitive than method calls)
+  get title(): string | undefined {
+    return this.tag().title;
+  }
+
+  set title(value: string | undefined) {
+    if (value !== undefined) {
+      this.setTitle(value);
+    }
+  }
+
+  get artist(): string | undefined {
+    return this.tag().artist;
+  }
+
+  set artist(value: string | undefined) {
+    if (value !== undefined) {
+      this.setArtist(value);
+    }
+  }
+
+  get album(): string | undefined {
+    return this.tag().album;
+  }
+
+  set album(value: string | undefined) {
+    if (value !== undefined) {
+      this.setAlbum(value);
+    }
+  }
+
+  // Async operations with callbacks
+  tagAsync(callback: TagLibCallback<any>): void {
+    try {
+      const tags = this.tag();
+      callback(null, tags);
+    } catch (error) {
+      const tagLibError: TagLibError = {
+        name: 'TagLibError',
+        message: error.message,
+        code: 'MEMORY_ERROR',
+      };
+      callback(tagLibError);
+    }
+  }
+
+  saveAsync(callback: TagLibCallback<boolean>): void {
+    try {
+      const result = this.save();
+      callback(null, result);
+    } catch (error) {
+      const tagLibError: TagLibError = {
+        name: 'TagLibError', 
+        message: error.message,
+        code: 'PERMISSION_DENIED',
+      };
+      callback(tagLibError);
+    }
+  }
+
+  // Bulk tag setting (convenience method)
+  setTags(tags: {
+    title?: string;
+    artist?: string;
+    album?: string;
+    year?: number;
+    genre?: string;
+    track?: number;
+    comment?: string;
+  }): void {
+    Object.entries(tags).forEach(([key, value]) => {
+      if (value !== undefined) {
+        (this as any)[key] = value;
+      }
+    });
+  }
+
+  // Enhanced error handling for save operations
+  saveWithValidation(): { success: boolean; errors: TagLibError[] } {
+    const errors: TagLibError[] = [];
+    
+    try {
+      // Validate before saving
+      if (!this.isValid()) {
+        errors.push({
+          name: 'TagLibError',
+          message: 'File is not valid for writing',
+          code: 'INVALID_FORMAT',
+        });
+      }
+
+      const success = this.save();
+      return { success, errors };
+    } catch (error) {
+      errors.push({
+        name: 'TagLibError',
+        message: error.message,
+        code: 'PERMISSION_DENIED',
+      });
+      return { success: false, errors };
+    }
+  }
+
+  // Method stubs (would delegate to existing implementation)
+  private tag(): any { throw new Error("Not implemented"); }
+  private setTitle(title: string): void { throw new Error("Not implemented"); }
+  private setArtist(artist: string): void { throw new Error("Not implemented"); }
+  private setAlbum(album: string): void { throw new Error("Not implemented"); }
+  private save(): boolean { throw new Error("Not implemented"); }
+  private isValid(): boolean { throw new Error("Not implemented"); }
+}
+
+/**
+ * Usage examples demonstrating enhanced API
+ */
+export function demonstrateEnhancedAPI() {
+  // Example 1: Property-based access
+  const file = new EnhancedAudioFile();
+  file.title = "New Song";
+  file.artist = "New Artist";
+  console.log(`${file.artist} - ${file.title}`);
+
+  // Example 2: Bulk tag setting
+  file.setTags({
+    title: "Song Title",
+    artist: "Artist Name",
+    album: "Album Name",
+    year: 2024,
+  });
+
+  // Example 3: Enhanced error handling
+  const result = file.saveWithValidation();
+  if (!result.success) {
+    result.errors.forEach(error => {
+      console.error(`Error ${error.code}: ${error.message}`);
+    });
+  }
+
+  // Example 4: Callback-style async operations
+  file.tagAsync((err, tags) => {
+    if (err) {
+      console.error(`Failed to read tags: ${err.message}`);
+      return;
+    }
+    console.log('Tags:', tags);
+  });
+}

package/src/mod.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview TagLib WebAssembly TypeScript bindings
+ * Universal audio metadata handling for Deno, Node.js, and browsers
+ */
+
+export * from "./taglib.ts";
+export * from "./types.ts";
+export { type TagLibModule } from "./wasm.ts";

package/src/taglib.ts

@@ -0,0 +1,441 @@
+/**
+ * @fileoverview Main TagLib API wrapper
+ */
+
+import type {
+  AudioFormat,
+  AudioProperties,
+  ExtendedTag,
+  FieldMapping,
+  Picture,
+  PropertyMap,
+  Tag,
+  TagLibConfig,
+} from "./types.ts";
+import { METADATA_MAPPINGS } from "./types.ts";
+import {
+  cStringToJS,
+  jsToCString,
+  loadTagLibModule,
+  type TagLibModule,
+} from "./wasm.ts";
+
+/**
+ * Represents an audio file with metadata and properties
+ */
+export class AudioFile {
+  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);
+    this.propsPtr = module._taglib_file_audioproperties(fileId);
+  }
+
+  /**
+   * Check if the file is valid and was loaded successfully
+   */
+  isValid(): boolean {
+    return this.module._taglib_file_is_valid(this.fileId) !== 0;
+  }
+
+  /**
+   * Get the file format
+   */
+  format(): AudioFormat {
+    const formatPtr = this.module._taglib_file_format(this.fileId);
+    if (formatPtr === 0) return "MP3"; // fallback
+    const formatStr = cStringToJS(this.module, formatPtr);
+    return formatStr as AudioFormat;
+  }
+
+  /**
+   * Get basic tag information
+   */
+  tag(): Tag {
+    if (this.tagPtr === 0) return {};
+
+    const title = this.module._taglib_tag_title(this.tagPtr);
+    const artist = this.module._taglib_tag_artist(this.tagPtr);
+    const album = this.module._taglib_tag_album(this.tagPtr);
+    const comment = this.module._taglib_tag_comment(this.tagPtr);
+    const genre = this.module._taglib_tag_genre(this.tagPtr);
+    const year = this.module._taglib_tag_year(this.tagPtr);
+    const track = this.module._taglib_tag_track(this.tagPtr);
+
+    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.)
+   */
+  audioProperties(): AudioProperties | null {
+    if (this.propsPtr === 0) return null;
+
+    const length = this.module._taglib_audioproperties_length(this.propsPtr);
+    const bitrate = this.module._taglib_audioproperties_bitrate(this.propsPtr);
+    const sampleRate = this.module._taglib_audioproperties_samplerate(
+      this.propsPtr,
+    );
+    const channels = this.module._taglib_audioproperties_channels(
+      this.propsPtr,
+    );
+
+    return {
+      length,
+      bitrate,
+      sampleRate,
+      channels,
+      format: this.format(),
+    };
+  }
+
+  /**
+   * Set the title tag
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  setYear(year: number): void {
+    if (this.tagPtr === 0) return;
+    this.module._taglib_tag_set_year(this.tagPtr, year);
+  }
+
+  /**
+   * Set the track number tag
+   */
+  setTrack(track: number): void {
+    if (this.tagPtr === 0) return;
+    this.module._taglib_tag_set_track(this.tagPtr, track);
+  }
+
+  /**
+   * Save changes to the file
+   */
+  save(): boolean {
+    return this.module._taglib_file_save(this.fileId) !== 0;
+  }
+
+  /**
+   * Get extended metadata with format-agnostic field names
+   */
+  extendedTag(): ExtendedTag {
+    // Get basic tags first
+    const basicTag = this.tag();
+    
+    // TODO: Implement advanced metadata reading via PropertyMap
+    // For now, return basic tags with placeholder for advanced fields
+    return {
+      ...basicTag,
+      // Advanced fields 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,
+      // ReplayGain fields
+      replayGainTrackGain: undefined,
+      replayGainTrackPeak: undefined,
+      replayGainAlbumGain: undefined,
+      replayGainAlbumPeak: undefined,
+      // Apple Sound Check
+      appleSoundCheck: undefined,
+    };
+  }
+
+  /**
+   * Set extended metadata using format-agnostic field names
+   * The library automatically maps fields to the correct format-specific storage
+   */
+  setExtendedTag(tag: Partial<ExtendedTag>): void {
+    // Set basic tags using existing methods
+    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);
+    
+    // TODO: Implement advanced metadata writing via PropertyMap
+    // For fields like acoustidFingerprint, acoustidId, etc.
+  }
+
+  /**
+   * Set AcoustID fingerprint (format-agnostic)
+   * Automatically stores in the correct location for each format:
+   * - MP3: TXXX frame with "Acoustid Fingerprint" description
+   * - FLAC/OGG: ACOUSTID_FINGERPRINT Vorbis comment
+   * - MP4: ----:com.apple.iTunes:Acoustid Fingerprint atom
+   */
+  setAcoustidFingerprint(fingerprint: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setAcoustidFingerprint: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get AcoustID fingerprint (format-agnostic)
+   */
+  getAcoustidFingerprint(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set AcoustID UUID (format-agnostic)
+   * Automatically stores in the correct location for each format:
+   * - MP3: TXXX frame with "Acoustid Id" description  
+   * - FLAC/OGG: ACOUSTID_ID Vorbis comment
+   * - MP4: ----:com.apple.iTunes:Acoustid Id atom
+   */
+  setAcoustidId(id: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setAcoustidId: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get AcoustID UUID (format-agnostic)
+   */
+  getAcoustidId(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set MusicBrainz Track ID (format-agnostic)
+   */
+  setMusicBrainzTrackId(id: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setMusicBrainzTrackId: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get MusicBrainz Track ID (format-agnostic)
+   */
+  getMusicBrainzTrackId(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set ReplayGain track gain (format-agnostic)
+   * Automatically stores in the correct location for each format:
+   * - MP3: TXXX frame with "ReplayGain_Track_Gain" description
+   * - FLAC/OGG: REPLAYGAIN_TRACK_GAIN Vorbis comment
+   * - MP4: ----:com.apple.iTunes:replaygain_track_gain atom
+   */
+  setReplayGainTrackGain(gain: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setReplayGainTrackGain: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get ReplayGain track gain (format-agnostic)
+   */
+  getReplayGainTrackGain(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set ReplayGain track peak (format-agnostic)
+   */
+  setReplayGainTrackPeak(peak: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setReplayGainTrackPeak: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get ReplayGain track peak (format-agnostic)
+   */
+  getReplayGainTrackPeak(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set ReplayGain album gain (format-agnostic)
+   */
+  setReplayGainAlbumGain(gain: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setReplayGainAlbumGain: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get ReplayGain album gain (format-agnostic)
+   */
+  getReplayGainAlbumGain(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set ReplayGain album peak (format-agnostic)
+   */
+  setReplayGainAlbumPeak(peak: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setReplayGainAlbumPeak: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get ReplayGain album peak (format-agnostic)
+   */
+  getReplayGainAlbumPeak(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Set Apple Sound Check normalization data (format-agnostic)
+   * Automatically stores in the correct location for each format:
+   * - MP3: TXXX frame with "iTunNORM" description
+   * - FLAC/OGG: ITUNNORM Vorbis comment
+   * - MP4: ----:com.apple.iTunes:iTunNORM atom
+   */
+  setAppleSoundCheck(iTunNORM: string): void {
+    // TODO: Implement format-specific storage
+    console.warn("setAppleSoundCheck: Advanced metadata not yet implemented");
+  }
+
+  /**
+   * Get Apple Sound Check normalization data (format-agnostic)
+   */
+  getAppleSoundCheck(): string | undefined {
+    // TODO: Implement format-specific reading
+    return undefined;
+  }
+
+  /**
+   * Clean up resources
+   */
+  dispose(): void {
+    if (this.fileId !== 0) {
+      this.module._taglib_file_delete(this.fileId);
+      this.fileId = 0;
+    }
+  }
+}
+
+/**
+ * Main TagLib class for creating and managing audio files
+ */
+export class TagLib {
+  private module: TagLibModule;
+
+  private constructor(module: TagLibModule) {
+    this.module = module;
+  }
+
+  /**
+   * Initialize TagLib with optional configuration
+   */
+  static async initialize(config?: TagLibConfig): Promise<TagLib> {
+    const module = await loadTagLibModule(config);
+    return new TagLib(module);
+  }
+
+  /**
+   * Open an audio file from a buffer
+   */
+  openFile(buffer: Uint8Array): AudioFile {
+    if (!this.module.HEAPU8) {
+      throw new Error("WASM module not properly initialized - missing HEAPU8");
+    }
+    
+    // Use Emscripten's allocate function for proper memory management
+    const dataPtr = this.module.allocate(buffer, this.module.ALLOC_NORMAL);
+
+    const fileId = this.module._taglib_file_new_from_buffer(
+      dataPtr,
+      buffer.length,
+    );
+
+    if (fileId === 0) {
+      // Don't free memory immediately to debug reuse issue
+      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 temporary buffer copy (TagLib has made its own copy in ByteVector)
+    this.module._free(dataPtr);
+
+    return new AudioFile(this.module, fileId);
+  }
+
+  /**
+   * Get the underlying WASM module (for advanced usage)
+   */
+  getModule(): TagLibModule {
+    return this.module;
+  }
+}