@uswriting/exiftool

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

Installation

npm install @uswriting/exiftool

Description

This package provides a WebAssembly-based implementation of ExifTool that works in both browser and Node.js environments. It leverages zeroperl to execute ExifTool without requiring any native binaries or system dependencies.

Usage

Parsing Metadata

Basic Usage

import { parseMetadata } from '@uswriting/exiftool';

// Browser usage with File API
document.querySelector('input[type="file"]').addEventListener('change', async (event) => {
  const file = event.target.files[0];
  const result = await parseMetadata(file);
  
  if (result.success) {
    console.log(result.data);
  } else {
    console.error('Error:', result.error);
  }
});

Extracting Specific Metadata

import { parseMetadata } from '@uswriting/exiftool';

const result = await parseMetadata(file, {
  args: ['-Author', '-CreateDate', '-Make', '-Model']
});

if (result.success) {
  console.log(result.data);
}

JSON Output

import { parseMetadata } from '@uswriting/exiftool';

const result = await parseMetadata(file, {
  args: ['-json', '-n'],
  transform: (data) => JSON.parse(data)
});

if (result.success) {
  // Typed access to properties
  console.log(result.data); // { ... }
}

Writing Metadata

Basic Usage

This example demonstrates writing basic XMP tags to a selected file using a string array for tags.

import { writeMetadata, ExifToolWriteOptions } from '@uswriting/exiftool';

// 'selectedFile' is a File object obtained from user input.

if (selectedFile) {
  const tagsToWrite: string[] = [
    "-XMP-dc:Description=My test image",
    "-XMP-photoshop:Credit=Photographer Name",
    "-XMP-dc:Subject=Nature, Landscape"
  ];

  const options: ExifToolWriteOptions = {
    tags: tagsToWrite
    // For more advanced options like 'configFile' or 'extraArgs',
    // refer to the API Reference for ExifToolWriteOptions.
  };

  const result = await writeMetadata(selectedFile, options);

  if (result.success) {
    // Modified file contents
    console.log(result.data);  // { ... }
  }
}

Important Notes

• In browser environments, pass the File object directly from file inputs. Do not convert it to an ArrayBuffer or Uint8Array.
• The writeMetadata function returns a new Uint8Array containing the modified file data. The original file object is not changed.
• This package uses asynchronous web APIs for file processing which allows handling files over 2GB without loading them entirely into memory.
• ExifTool is executed entirely within the browser or Node.js environment - no server requests are made for metadata extraction.

API Reference

parseMetadata()

async function parseMetadata<TReturn = string>(
  file: Binaryfile | File,
  options: ExifToolOptions<TReturn> = {}
): Promise<ExifToolOutput<TReturn>>

Parameters

• file: Either a browser File object or a Binaryfile object with name and data properties.
• options: Configuration options for the metadata extraction.

ExifToolOptions

interface ExifToolOptions<TReturn> {
  // Additional command-line arguments to pass to ExifTool
  args?: string[];
  
  // Custom fetch implementation for loading the WASM module
  fetch?: (...args: any[]) => Promise<Response>;
  
  // Transform the raw ExifTool output into a different format
  transform?: (data: string) => TReturn;
}

Return Value (ExifToolOutput)

Returns a Promise that resolves to an ExifToolOutput object:

type ExifToolOutput<TOutput> =
  | {
      success: true;
      data: TOutput;
      error: string;
      exitCode: 0;
    }
  | {
      success: false;
      data: undefined;
      error: string;
      exitCode: number | undefined;
    };

writeMetadata()

async function writeMetadata(
  file: Binaryfile | File,
  options: ExifToolWriteOptions
): Promise<ExifToolWriteResult>

Parameters

• file: Either a browser File object or a Binaryfile object ({ name: string, data: Uint8Array | Blob }) representing the file to modify.
• options: Configuration options for writing metadata.

ExifToolWriteOptions

// Defines possible values for a tag when using TagsObject.
type TagValue = string | number | boolean | (string | number | boolean)[];

// Represents tags as a JavaScript object for writing metadata.
type TagsObject = Record<string, TagValue>;

interface ExifToolWriteOptions {
  // Tags to write. Can be an array of ExifTool arguments (e.g., `["-Comment=Test"]`)
  // or a `TagsObject` (e.g., `{ "Comment": "Test", "IPTC:Keywords": ["one", "two"] }`).
  tags: string[] | TagsObject;

  // Optional: Custom ExifTool config file for defining custom tags.
  // Provide as { name: string, data: Uint8Array }.
  configFile?: {
    name: string;
    data: Uint8Array;
  };

  // Custom fetch implementation for loading the WASM module.
  fetch?: (...args: any[]) => Promise<Response>;

  // Additional command-line arguments for ExifTool (e.g., `-m` for ignore minor errors).
  // Avoid input/output filenames or tag assignments here.
  extraArgs?: string[];
}

Return Value (ExifToolWriteResult)

Returns a Promise that resolves to an ExifToolWriteResult object:

type ExifToolWriteResult =
  | {
      success: true;
      data: Uint8Array;
      warnings: string;
      exitCode: 0;
    }
  | {
      success: false;
      data: undefined;
      error: string;
      exitCode: number | undefined;
    };

License

Apache License, Version 2.0