taglib-wasm 0.3.3 → 0.3.9

package/dist/src/types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * @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
+ */
+export type { TagLibModule } from "./wasm.ts";
+/**
+ * Supported file types detected by TagLib.
+ * "UNKNOWN" indicates the format could not be determined.
+ *
+ * @example
+ * ```typescript
+ * const file = await taglib.open(buffer);
+ * const format = file.getFormat();
+ * if (format === "MP3") {
+ *   // Handle MP3-specific features
+ * }
+ * ```
+ */
+export type FileType = "MP3" | "MP4" | "FLAC" | "OGG" | "OPUS" | "WAV" | "AIFF" | "UNKNOWN";
+/**
+ * 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" | "MP4" | "M4A" | "FLAC" | "OGG" | "OPUS" | "WAV" | "AIFF" | "WMA" | "APE" | "MPC" | "TTA" | "WV" | "MOD" | "IT" | "S3M" | "XM";
+/**
+ * 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 */
+    readonly length: number;
+    /** Bitrate in kb/s */
+    readonly bitrate: number;
+    /** Sample rate in Hz */
+    readonly sampleRate: number;
+    /** Number of audio channels */
+    readonly channels: number;
+}
+/**
+ * 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 */
+    title?: string;
+    /** Artist name */
+    artist?: string;
+    /** Album name */
+    album?: string;
+    /** Comment */
+    comment?: string;
+    /** Genre */
+    genre?: string;
+    /** Year */
+    year?: number;
+    /** Track number */
+    track?: number;
+}
+/**
+ * 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) */
+    acoustidFingerprint?: string;
+    /** AcoustID UUID */
+    acoustidId?: string;
+    /** MusicBrainz Track ID */
+    musicbrainzTrackId?: string;
+    /** MusicBrainz Release ID */
+    musicbrainzReleaseId?: string;
+    /** MusicBrainz Artist ID */
+    musicbrainzArtistId?: string;
+    /** MusicBrainz Release Group ID */
+    musicbrainzReleaseGroupId?: string;
+    /** Album artist (different from track artist) */
+    albumArtist?: string;
+    /** Composer */
+    composer?: string;
+    /** Disc number */
+    discNumber?: number;
+    /** Total tracks on album */
+    totalTracks?: number;
+    /** Total discs in release */
+    totalDiscs?: number;
+    /** BPM (beats per minute) */
+    bpm?: number;
+    /** Compilation flag */
+    compilation?: boolean;
+    /** Sort title for alphabetization */
+    titleSort?: string;
+    /** Sort artist for alphabetization */
+    artistSort?: string;
+    /** Sort album for alphabetization */
+    albumSort?: string;
+    /** ReplayGain track gain in dB (e.g., "-6.54 dB") */
+    replayGainTrackGain?: string;
+    /** ReplayGain track peak value (0.0-1.0) */
+    replayGainTrackPeak?: string;
+    /** ReplayGain album gain in dB */
+    replayGainAlbumGain?: string;
+    /** ReplayGain album peak value (0.0-1.0) */
+    replayGainAlbumPeak?: string;
+    /** Apple Sound Check normalization data (iTunNORM) */
+    appleSoundCheck?: string;
+}
+/**
+ * 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 */
+    id3v2?: {
+        frame: string;
+        description?: string;
+    };
+    /** FLAC/OGG Vorbis Comments mapping */
+    vorbis?: string;
+    /** MP4/M4A atom mapping */
+    mp4?: string;
+    /** WAV INFO chunk mapping */
+    wav?: string;
+}
+/**
+ * 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 declare const METADATA_MAPPINGS: Record<keyof ExtendedTag, FieldMapping>;
+/**
+ * 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[];
+}
+/**
+ * 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 */
+    mimeType: string;
+    /** Image data */
+    data: Uint8Array;
+    /** Picture type (front cover, back cover, etc.) */
+    type: PictureType;
+    /** Description */
+    description?: string;
+}
+/**
+ * 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 declare enum PictureType {
+    Other = 0,
+    FileIcon = 1,
+    OtherFileIcon = 2,
+    FrontCover = 3,
+    BackCover = 4,
+    LeafletPage = 5,
+    Media = 6,
+    LeadArtist = 7,
+    Artist = 8,
+    Conductor = 9,
+    Band = 10,
+    Composer = 11,
+    Lyricist = 12,
+    RecordingLocation = 13,
+    DuringRecording = 14,
+    DuringPerformance = 15,
+    MovieScreenCapture = 16,
+    ColouredFish = 17,
+    Illustration = 18,
+    BandLogo = 19,
+    PublisherLogo = 20
+}
+/**
+ * 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 = "Constant" | "LongTermAverage" | "VariableConstrained" | "Variable";
+/**
+ * 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 declare const BITRATE_CONTROL_MODE_VALUES: Record<BitrateControlMode, number>;
+/**
+ * Map of numeric values to bitrate control mode names.
+ * Used for converting numeric codes from MP4/M4A files
+ * to human-readable string representations.
+ */
+export declare const BITRATE_CONTROL_MODE_NAMES: Record<number, BitrateControlMode>;
+/**
+ * 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 */
+    memory?: {
+        /** Initial memory size in bytes */
+        initial?: number;
+        /** Maximum memory size in bytes */
+        maximum?: number;
+    };
+    /** Enable debug output */
+    debug?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

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