taglib-wasm/dist/src/file-utils.d.ts

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

/**
 * @fileoverview File I/O utilities for working with cover art in taglib-wasm
 *
 * This module provides file system helpers for saving and loading cover art
 * in Node.js, Deno, and Bun environments.
 *
 * @example
 * ```typescript
 * import { exportCoverArt, importCoverArt } from "taglib-wasm/file-utils";
 *
 * // Export cover art from audio file to image file
 * await exportCoverArt("song.mp3", "cover.jpg");
 *
 * // Import cover art from image file to audio file
 * await importCoverArt("song.mp3", "new-cover.png");
 * ```
 */
import type { Picture, PictureType } from "./types.ts";
/**
 * Export cover art from an audio file to an image file
 *
 * Extracts the primary cover art (front cover if available, otherwise first picture)
 * and saves it to the specified path.
 *
 * @param audioPath - Path to the audio file
 * @param imagePath - Path where the image should be saved
 * @returns Promise that resolves when the image is saved
 * @throws Error if no cover art is found
 *
 * @example
 * ```typescript
 * // Export cover art as JPEG
 * await exportCoverArt("album/track01.mp3", "album/cover.jpg");
 * ```
 */
export declare function exportCoverArt(audioPath: string, imagePath: string): Promise<void>;
/**
 * Export a specific picture type from an audio file
 *
 * @param audioPath - Path to the audio file
 * @param imagePath - Path where the image should be saved
 * @param type - Picture type to export
 * @returns Promise that resolves when the image is saved
 * @throws Error if no picture of the specified type is found
 *
 * @example
 * ```typescript
 * // Export back cover
 * await exportPictureByType(
 *   "album/track01.mp3",
 *   "album/back-cover.jpg",
 *   PictureType.BackCover
 * );
 * ```
 */
export declare function exportPictureByType(audioPath: string, imagePath: string, type: PictureType | number): Promise<void>;
/**
 * Export all pictures from an audio file
 *
 * Saves each picture with a numbered suffix based on its type and index.
 *
 * @param audioPath - Path to the audio file
 * @param outputDir - Directory where images should be saved
 * @param options - Export options
 * @returns Promise resolving to array of created file paths
 *
 * @example
 * ```typescript
 * // Export all pictures to a directory
 * const files = await exportAllPictures("song.mp3", "./artwork/");
 * console.log(`Exported ${files.length} pictures`);
 * ```
 */
export declare function exportAllPictures(audioPath: string, outputDir: string, options?: {
    nameFormat?: (picture: Picture, index: number) => string;
}): Promise<string[]>;
/**
 * Import cover art from an image file to an audio file
 *
 * Replaces all existing pictures with a single front cover from the image file.
 * The audio file is modified in place.
 *
 * @param audioPath - Path to the audio file to update
 * @param imagePath - Path to the image file to import
 * @param options - Import options
 * @returns Promise that resolves when the audio file is updated
 *
 * @example
 * ```typescript
 * // Replace cover art with a new image
 * await importCoverArt("song.mp3", "new-cover.jpg");
 * ```
 */
export declare function importCoverArt(audioPath: string, imagePath: string, options?: {
    mimeType?: string;
    description?: string;
}): Promise<void>;
/**
 * Import a picture from file with specific type
 *
 * Adds or replaces a picture of the specified type in the audio file.
 * The audio file is modified in place.
 *
 * @param audioPath - Path to the audio file to update
 * @param imagePath - Path to the image file to import
 * @param type - Picture type to set
 * @param options - Import options
 * @returns Promise that resolves when the audio file is updated
 *
 * @example
 * ```typescript
 * // Add a back cover
 * await importPictureWithType(
 *   "song.mp3",
 *   "back-cover.jpg",
 *   PictureType.BackCover,
 *   { description: "Album back cover" }
 * );
 * ```
 */
export declare function importPictureWithType(audioPath: string, imagePath: string, type: PictureType | number, options?: {
    mimeType?: string;
    description?: string;
}): Promise<void>;
/**
 * Load a picture from an image file
 *
 * @param imagePath - Path to the image file
 * @param type - Picture type (defaults to FrontCover)
 * @param options - Picture options
 * @returns Picture object ready to be applied to audio files
 *
 * @example
 * ```typescript
 * const frontCover = await loadPictureFromFile("cover.jpg");
 * const backCover = await loadPictureFromFile("back.png", PictureType.BackCover);
 *
 * const modifiedBuffer = await applyPictures("song.mp3", [frontCover, backCover]);
 * ```
 */
export declare function loadPictureFromFile(imagePath: string, type?: PictureType | number, options?: {
    mimeType?: string;
    description?: string;
}): Promise<Picture>;
/**
 * Save a picture to an image file
 *
 * @param picture - Picture object to save
 * @param imagePath - Path where the image should be saved
 * @returns Promise that resolves when the image is saved
 *
 * @example
 * ```typescript
 * const pictures = await readPictures("song.mp3");
 * for (const picture of pictures) {
 *   await savePictureToFile(picture, `export-${picture.type}.jpg`);
 * }
 * ```
 */
export declare function savePictureToFile(picture: Picture, imagePath: string): Promise<void>;
/**
 * Copy cover art from one audio file to another
 *
 * @param sourcePath - Path to source audio file
 * @param targetPath - Path to target audio file (modified in place)
 * @param options - Copy options
 * @returns Promise that resolves when cover art is copied
 * @throws Error if source has no cover art
 *
 * @example
 * ```typescript
 * // Copy cover art from one file to another
 * await copyCoverArt("album/track01.mp3", "album/track02.mp3");
 *
 * // Copy all pictures
 * await copyCoverArt("source.mp3", "target.mp3", { copyAll: true });
 * ```
 */
export declare function copyCoverArt(sourcePath: string, targetPath: string, options?: {
    copyAll?: boolean;
}): Promise<void>;
/**
 * Check if cover art files exist for an audio file
 *
 * Looks for common cover art filenames in the same directory as the audio file.
 *
 * @param audioPath - Path to the audio file
 * @returns Object with found cover art paths
 *
 * @example
 * ```typescript
 * const covers = await findCoverArtFiles("music/album/track01.mp3");
 * if (covers.front) {
 *   await importCoverArt("music/album/track01.mp3", covers.front);
 * }
 * ```
 */
export declare function findCoverArtFiles(audioPath: string): Promise<{
    front?: string;
    back?: string;
    folder?: string;
    [key: string]: string | undefined;
}>;
//# sourceMappingURL=file-utils.d.ts.map