@uswriting/exiftool/dist/cjs/types/index.d.ts

ExifTool powered by WebAssembly to extract and write metadata from files in browsers and Node.js environments using zeroperl

type FetchLike = (...args: unknown[]) => Promise<Response>;
export type ExifTags = Record<string, string | number | boolean | (string | number | boolean)[]>;
/**
 * Configuration options for parsing file metadata with ExifTool
 * @template TransformReturn The type of the transformed output data
 */
export interface ExifToolOptions<TransformReturn = unknown> {
    /**
     * Additional command-line arguments to pass to ExifTool
     *
     * @example
     * // Extract specific tags
     * args: ["-Author", "-CreateDate"]
     *
     * @example
     * // Output as JSON
     * args: ["-json", "-n"]
     *
     * @see https://exiftool.org/exiftool_pod.html for all available options
     */
    args?: string[];
    /**
     * Custom fetch implementation for loading the WASM module
     *
     * Only needed for environments with custom fetch polyfills
     */
    fetch?: FetchLike;
    /**
     * Transform the raw ExifTool output into a different format
     *
     * @example
     * // Parse output as JSON
     * transform: (data) => JSON.parse(data)
     */
    transform?: (data: string) => TransformReturn;
    /**
     * The ExifTool_config
     */
    config?: Binaryfile | File;
}
/**
 * Represents a binary file for metadata extraction
 */
type Binaryfile = {
    /** Filename with extension (e.g., "image.jpg") */
    name: string;
    /** The binary content of the file */
    data: Uint8Array | Blob;
};
/**
 * Result of an ExifTool metadata extraction operation
 * @template TOutput The type of the output data after transformation
 */
type ExifToolOutput<TOutput> = {
    /** True when metadata was successfully extracted */
    success: true;
    /** The extracted metadata, transformed if a transform function was provided */
    data: TOutput;
    /** Any warnings or info messages from ExifTool */
    error: string;
    /** Always 0 for success */
    exitCode: 0;
} | {
    /** False when metadata extraction failed */
    success: false;
    /** No data available on failure */
    data: undefined;
    /** Error message explaining why the operation failed */
    error: string;
    /** Non-zero exit code indicating the type of failure */
    exitCode: number | undefined;
};
/**
 * Extract metadata from a file using ExifTool
 *
 * @template TReturn Type of the returned data after transformation (defaults to string)
 * @param file File to extract metadata from
 * @param options Configuration options
 * @returns Promise resolving to the extraction result
 *
 * @example
 * // Basic usage with browser File object
 * const input = document.querySelector('input[type="file"]');
 * input.addEventListener('change', async () => {
 *   const file = input.files[0];
 *   const result = await parseMetadata(file);
 *   if (result.success) {
 *     console.log(result.data); // Raw ExifTool output as string
 *   }
 * });
 *
 * @example
 * // Extract specific tags and transform to JSON
 * const result = await parseMetadata(file, {
 *   args: ["-json"],
 *   transform: (data) => JSON.parse(data)
 * });
 * if (result.success) {
 *   console.log(result.data); // Typed access to specific metadata
 * }
 */
export declare function parseMetadata<TReturn = string>(file: Binaryfile | File, options?: ExifToolOptions<TReturn>): Promise<ExifToolOutput<TReturn>>;
/**
 * Write metadata to a file using ExifTool
 *
 * This function modifies an existing file by writing new metadata tags or updating existing ones.
 * The operation runs entirely in the browser using WebAssembly without requiring server uploads.
 *
 * @template TReturn Type of the returned data after transformation (defaults to Uint8Array)
 * @param file File to write metadata to (Browser File object or Binaryfile)
 * @param tags Object containing metadata tags to write, where keys are tag names and values are tag values
 * @param options Configuration options for the write operation
 * @returns Promise resolving to the write operation result containing the modified file data
 *
 * @example
 * // Basic usage with browser File object
 * const input = document.querySelector('input[type="file"]');
 * input.addEventListener('change', async () => {
 *   const file = input.files[0];
 *   const result = await writeMetadata(file, {
 *     'Author': 'John Doe',
 *     'Title': 'My Photo',
 *     'Keywords': 'nature,photography'
 *   });
 *
 *   if (result.success) {
 *     // result.data contains the modified file as Uint8Array
 *     const modifiedBlob = new Blob([result.data]);
 *     // Save or use the modified file
 *   }
 * });
 *
 * @example
 * // Writing multiple tag types
 * const result = await writeMetadata(file, {
 *   'Author': 'Jane Smith',
 *   'Rating': 5,
 *   'Keywords': ['landscape', 'sunset', 'beach'],
 *   'GPS:GPSLatitude': 40.7128,
 *   'GPS:GPSLongitude': -74.0060,
 *   'EXIF:Copyright': '© 2025 Jane Smith'
 * });
 *
 * @example
 * // Using with custom ExifTool config
 * const result = await writeMetadata(file, tags, {
 *   config: configFile,
 *   args: ['-overwrite_original', '-P']
 * });
 *
 * @example
 * // Handle errors properly
 * try {
 *   const result = await writeMetadata(file, tags);
 *   if (result.success) {
 *     console.log('Metadata written successfully');
 *     downloadFile(result.data, `modified_${file.name}`);
 *   } else {
 *     console.error('Write failed:', result.error);
 *   }
 * } catch (error) {
 *   console.error('Operation failed:', error);
 * }
 *
 * @remarks
 * - The function creates a temporary output file internally and returns its contents
 * - Original file is not modified in place; a new file with metadata is generated
 * - Supports all ExifTool-compatible metadata formats (EXIF, IPTC, XMP, etc.)
 * - Tag names should follow ExifTool conventions (e.g., 'EXIF:Artist', 'XMP:Creator')
 * - Array values in tags are automatically converted to multiple ExifTool arguments
 * - The returned Uint8Array can be converted to a Blob for download or further processing
 *
 * @see {@link https://exiftool.org/TagNames/index.html} for complete tag reference
 * @see {@link parseMetadata} for reading metadata from files
 *
 * @since 1.0.4
 */
export declare function writeMetadata(file: Binaryfile | File, tags: ExifTags, options?: ExifToolOptions): Promise<ExifToolOutput<ArrayBuffer>>;
export {};