Skip to content

CONFIGURATION.md

Latest commit

 

History

History
133 lines (96 loc) · 3.86 KB

CONFIGURATION.md

File metadata and controls

133 lines (96 loc) · 3.86 KB

Configuration Guide

exiftool-vendored provides two levels of configuration:

  1. Settings - Library-wide configuration affecting all ExifTool instances
  2. ExifToolOptions - Per-instance configuration

Quick Start

import { ExifTool, Settings } from "exiftool-vendored";

// Use the singleton for simple cases
import { exiftool } from "exiftool-vendored";
const tags = await exiftool.read("photo.jpg");

// Or create a custom instance
const et = new ExifTool({
  maxProcs: 4,
  taskTimeoutMillis: 30000,
});

Library-wide Settings

The Settings object provides global configuration:

import { Settings } from "exiftool-vendored";

// Enable historical timezone offsets for archival photos
Settings.allowArchaicTimezoneOffsets.value = true;

// Observe setting changes
const unsubscribe = Settings.allowArchaicTimezoneOffsets.onChange(
  (oldValue, newValue) => console.log(`Changed: ${oldValue} -> ${newValue}`),
);

// Reset all settings to defaults
Settings.reset();

Available settings:

  • allowArchaicTimezoneOffsets - Parse historical timezone offsets (default: false)
  • allowBakerIslandTime - Accept UTC-12:00 timezone (default: false)
  • maxValidOffsetMinutes - Tolerance for GPS/UTC timezone inference (default: 30)
  • logger - Logging configuration (default: enabled when NODE_DEBUG=exiftool-vendored)

Per-instance Options

The ExifToolOptions interface provides detailed configuration for individual ExifTool instances.

Common Configurations

High-throughput processing:

const exiftool = new ExifTool({
  maxProcs: 8,
  maxTasksPerProcess: 1000,
  taskTimeoutMillis: 60000,
});

Timezone accuracy:

const exiftool = new ExifTool({
  backfillTimezones: true,
  inferTimezoneFromDatestamps: true,
  preferTimezoneInferenceFromGps: true,
});

Using geo-tz for accurate timezone lookup:

import { find } from "geo-tz";

const exiftool = new ExifTool({
  geoTz: (lat, lon) => find(lat, lon)[0],
});

Enable geolocation features:

const exiftool = new ExifTool({
  geolocation: true, // Requires ExifTool 12.78+
});

const tags = await exiftool.read("photo.jpg");
console.log(tags.GeolocationCity, tags.GeolocationCountryCode);

MWG composite tags:

const exiftool = new ExifTool({
  useMWG: true, // Recommended by ExifTool, enabled by default
});

Resource Cleanup

As of v35, Node.js will exit naturally without calling .end() — child processes are cleaned up automatically.

For long-running applications (servers, daemons), calling .end() is still recommended for graceful shutdown. You can use disposables (TypeScript 5.2+) or manual cleanup:

// Disposables (TypeScript 5.2+)
{
  await using exiftool = new ExifTool();
  const tags = await exiftool.read("photo.jpg");
} // Automatic cleanup

// Manual cleanup
const exiftool = new ExifTool();
try {
  const tags = await exiftool.read("photo.jpg");
} finally {
  await exiftool.end();
}

API Reference

For complete documentation of all options with defaults: