taglib-wasm
Version:
TagLib for TypeScript platforms: Deno, Node.js, Bun, Electron, browsers, and Cloudflare Workers
179 lines • 6.22 kB
TypeScript
/**
* @fileoverview Web browser utilities for working with cover art in taglib-wasm
*
* This module provides browser-specific helpers for integrating taglib-wasm
* with web applications, including canvas integration and data URL support.
*
* @example
* ```typescript
* import { pictureToDataURL, setCoverArtFromCanvas } from "taglib-wasm/web-utils";
*
* // Display cover art in an <img> element
* const pictures = await readPictures("song.mp3");
* if (pictures.length > 0) {
* const dataURL = pictureToDataURL(pictures[0]);
* document.getElementById('cover').src = dataURL;
* }
*
* // Set cover art from a canvas
* const canvas = document.getElementById('myCanvas') as HTMLCanvasElement;
* const modifiedBuffer = await setCoverArtFromCanvas("song.mp3", canvas);
* ```
*/
import type { Picture, PictureType } from "./types.ts";
/**
* Convert a Picture object to a data URL for display in web browsers
*
* @param picture - Picture object from taglib-wasm
* @returns Data URL string that can be used as src for <img> elements
*
* @example
* ```typescript
* const pictures = await readPictures("song.mp3");
* const imgElement = document.getElementById('coverArt') as HTMLImageElement;
* imgElement.src = pictureToDataURL(pictures[0]);
* ```
*/
export declare function pictureToDataURL(picture: Picture): string;
/**
* Convert a data URL to a Picture object
*
* @param dataURL - Data URL string (e.g., "data:image/jpeg;base64,...")
* @param type - Picture type (defaults to FrontCover)
* @param description - Optional description
* @returns Picture object
*
* @example
* ```typescript
* const dataURL = canvas.toDataURL('image/jpeg');
* const picture = dataURLToPicture(dataURL, PictureType.FrontCover);
* const modifiedBuffer = await applyPictures("song.mp3", [picture]);
* ```
*/
export declare function dataURLToPicture(dataURL: string, type?: PictureType | number, description?: string): Picture;
/**
* Set cover art from an HTML canvas element
*
* @param file - File path, Uint8Array buffer, ArrayBuffer, or File object
* @param canvas - HTMLCanvasElement containing the image
* @param options - Options for image format and quality
* @returns Modified file buffer with cover art from canvas
*
* @example
* ```typescript
* const canvas = document.getElementById('albumArt') as HTMLCanvasElement;
* const modifiedBuffer = await setCoverArtFromCanvas("song.mp3", canvas, {
* format: 'image/jpeg',
* quality: 0.9
* });
* ```
*/
export declare function setCoverArtFromCanvas(file: string | Uint8Array | ArrayBuffer | File, canvas: HTMLCanvasElement, options?: {
format?: "image/jpeg" | "image/png" | "image/webp";
quality?: number;
type?: PictureType;
description?: string;
}): Promise<Uint8Array>;
/**
* Convert canvas to Picture object using blob for better performance
*
* This is more efficient than toDataURL for large images as it avoids
* the base64 encoding/decoding step.
*
* @param canvas - HTMLCanvasElement containing the image
* @param options - Options for image format and quality
* @returns Promise resolving to Picture object
*
* @example
* ```typescript
* const canvas = document.getElementById('albumArt') as HTMLCanvasElement;
* const picture = await canvasToPicture(canvas, {
* format: 'image/png',
* type: PictureType.BackCover
* });
* ```
*/
export declare function canvasToPicture(canvas: HTMLCanvasElement, options?: {
format?: "image/jpeg" | "image/png" | "image/webp";
quality?: number;
type?: PictureType;
description?: string;
}): Promise<Picture>;
/**
* Load an image file into a Picture object
*
* @param file - File object from <input type="file"> or drag-and-drop
* @param type - Picture type (defaults to FrontCover)
* @param description - Optional description
* @returns Promise resolving to Picture object
*
* @example
* ```typescript
* // From file input
* const input = document.getElementById('fileInput') as HTMLInputElement;
* input.addEventListener('change', async (e) => {
* const file = e.target.files[0];
* const picture = await imageFileToPicture(file);
* const modifiedBuffer = await applyPictures("song.mp3", [picture]);
* });
* ```
*/
export declare function imageFileToPicture(file: File, type?: PictureType | number, description?: string): Promise<Picture>;
/**
* Display a Picture in an HTML img element
*
* @param picture - Picture object from taglib-wasm
* @param imgElement - HTMLImageElement to display the picture in
*
* @example
* ```typescript
* const pictures = await readPictures("song.mp3");
* const img = document.getElementById('coverArt') as HTMLImageElement;
* displayPicture(pictures[0], img);
* ```
*/
export declare function displayPicture(picture: Picture, imgElement: HTMLImageElement): void;
/**
* Create a download link for a Picture
*
* @param picture - Picture object to download
* @param filename - Suggested filename for download
* @returns Temporary download URL (remember to revoke it after use)
*
* @example
* ```typescript
* const pictures = await readPictures("song.mp3");
* const downloadUrl = createPictureDownloadURL(pictures[0], "cover.jpg");
*
* const link = document.createElement('a');
* link.href = downloadUrl;
* link.download = "cover.jpg";
* link.click();
*
* // Clean up
* URL.revokeObjectURL(downloadUrl);
* ```
*/
export declare function createPictureDownloadURL(picture: Picture, filename?: string): string;
/**
* Extract all pictures and create a gallery
*
* @param file - Audio file to extract pictures from
* @param container - HTML element to append gallery items to
* @param options - Gallery display options
*
* @example
* ```typescript
* const galleryDiv = document.getElementById('pictureGallery');
* await createPictureGallery("song.mp3", galleryDiv, {
* className: 'album-art',
* includeDescription: true
* });
* ```
*/
export declare function createPictureGallery(file: string | Uint8Array | ArrayBuffer | File, container: HTMLElement, options?: {
className?: string;
includeDescription?: boolean;
onClick?: (picture: Picture, index: number) => void;
}): Promise<void>;
//# sourceMappingURL=web-utils.d.ts.map