taglib-wasm/dist/src/folder-api.d.ts

TagLib for TypeScript platforms: Deno, Node.js, Bun, Electron, browsers, and Cloudflare Workers

/**
 * Batch folder operations for taglib-wasm
 * Provides APIs for scanning directories and processing multiple audio files
 */
import { type Tag } from "./simple.ts";
import type { AudioProperties } from "./types.ts";
import { type TagLibWorkerPool } from "./worker-pool.ts";
/**
 * Metadata for a single audio file including path information
 */
/**
 * Audio dynamics data (ReplayGain and Apple Sound Check)
 */
export interface AudioDynamics {
    /** 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;
}
export interface AudioFileMetadata {
    /** Absolute or relative path to the audio file */
    path: string;
    /** Basic tag information (title, artist, album, etc.) */
    tags: Tag;
    /** Audio properties (duration, bitrate, sample rate, etc.) */
    properties?: AudioProperties;
    /** Whether the file contains embedded cover art */
    hasCoverArt?: boolean;
    /** Audio dynamics data (ReplayGain and Sound Check) */
    dynamics?: AudioDynamics;
    /** Any errors encountered while reading this file */
    error?: Error;
}
/**
 * Options for scanning folders
 */
export interface FolderScanOptions {
    /** Whether to scan subdirectories recursively (default: true) */
    recursive?: boolean;
    /** File extensions to include (default: common audio formats) */
    extensions?: string[];
    /** Maximum number of files to process (default: unlimited) */
    maxFiles?: number;
    /** Progress callback called after each file is processed */
    onProgress?: (processed: number, total: number, currentFile: string) => void;
    /** Whether to include audio properties (default: true) */
    includeProperties?: boolean;
    /** Whether to continue on errors (default: true) */
    continueOnError?: boolean;
    /** Use worker pool for parallel processing (default: true if available) */
    useWorkerPool?: boolean;
    /** Worker pool instance to use (creates one if not provided) */
    workerPool?: TagLibWorkerPool;
}
/**
 * Result of a folder scan operation
 */
export interface FolderScanResult {
    /** Successfully processed files with metadata */
    files: AudioFileMetadata[];
    /** Files that failed to process */
    errors: Array<{
        path: string;
        error: Error;
    }>;
    /** Total number of audio files found */
    totalFound: number;
    /** Total number of files successfully processed */
    totalProcessed: number;
    /** Time taken in milliseconds */
    duration: number;
}
/**
 * Scan a folder and read metadata from all audio files
 *
 * @param folderPath - Path to the folder to scan
 * @param options - Scanning options
 * @returns Metadata for all audio files found
 *
 * @example
 * ```typescript
 * // Scan a folder recursively
 * const result = await scanFolder("/path/to/music");
 * console.log(`Found ${result.totalFound} audio files`);
 * console.log(`Successfully processed ${result.totalProcessed} files`);
 *
 * // Process results
 * for (const file of result.files) {
 *   console.log(`${file.path}: ${file.tags.artist} - ${file.tags.title}`);
 * }
 *
 * // Scan with options
 * const result2 = await scanFolder("/path/to/music", {
 *   recursive: false,
 *   extensions: [".mp3", ".flac"],
 *   onProgress: (processed, total, file) => {
 *     console.log(`Processing ${processed}/${total}: ${file}`);
 *   }
 * });
 * ```
 */
export declare function scanFolder(folderPath: string, options?: FolderScanOptions): Promise<FolderScanResult>;
/**
 * Update metadata for multiple files in a folder
 *
 * @param updates - Array of objects containing path and tags to update
 * @param options - Update options
 * @returns Results of the update operation
 *
 * @example
 * ```typescript
 * // Update multiple files
 * const updates = [
 *   { path: "/music/song1.mp3", tags: { artist: "New Artist" } },
 *   { path: "/music/song2.mp3", tags: { album: "New Album" } }
 * ];
 *
 * const result = await updateFolderTags(updates);
 * console.log(`Updated ${result.successful} files`);
 * ```
 */
export declare function updateFolderTags(updates: Array<{
    path: string;
    tags: Partial<Tag>;
}>, options?: {
    continueOnError?: boolean;
    concurrency?: number;
}): Promise<{
    successful: number;
    failed: Array<{
        path: string;
        error: Error;
    }>;
    duration: number;
}>;
/**
 * Find duplicate audio files based on metadata
 *
 * @param folderPath - Path to scan for duplicates
 * @param criteria - Which fields to compare (default: artist and title)
 * @returns Groups of potential duplicate files
 */
export declare function findDuplicates(folderPath: string, criteria?: Array<keyof Tag>): Promise<Map<string, AudioFileMetadata[]>>;
/**
 * Export metadata from a folder to JSON
 *
 * @param folderPath - Path to scan
 * @param outputPath - Where to save the JSON file
 * @param options - Scan options
 */
export declare function exportFolderMetadata(folderPath: string, outputPath: string, options?: FolderScanOptions): Promise<void>;
//# sourceMappingURL=folder-api.d.ts.map