exiftool-vendored

Fast, cross-platform Node.js access to ExifTool. Built and supported by PhotoStructure.

Installation & Quick Start

Requirements: Node.js Active LTS or Maintenance LTS versions only

npm install exiftool-vendored
Copy

import { exiftool } from "exiftool-vendored";

// Read metadata
const tags = await exiftool.read("photo.jpg");
console.log(`Camera: ${tags.Make} ${tags.Model}`);
console.log(`Taken: ${tags.DateTimeOriginal}`);
console.log(`Size: ${tags.ImageWidth}x${tags.ImageHeight}`);

// Write metadata
await exiftool.write("photo.jpg", {
  XPComment: "Amazing sunset!",
  Copyright: "© 2024 Your Name",
});

// Extract thumbnail
await exiftool.extractThumbnail("photo.jpg", "thumb.jpg");

// The singleton instance automatically cleans up on process exit by default.
// If you need immediate cleanup or have disabled registerExitHandlers:
// await exiftool.end();
Copy

Why exiftool-vendored?

⚡ Performance

Order of magnitude faster than other Node.js ExifTool modules. Powers PhotoStructure and 1,000+ other projects.

🔧 Robust

• Cross-platform: macOS, Linux, Windows
• Comprehensive: Read, write, extract embedded images
• Reliable: Battle-tested with extensive test coverage

📚 Developer-Friendly

• TypeScript: Full type definitions for thousands of metadata fields
• Smart dates: Timezone-aware ExifDateTime classes
• Auto-generated tags: Based on 6,000+ real camera samples

Core Features

Reading Metadata

const tags = await exiftool.read("photo.jpg");

// Camera info
console.log(tags.Make, tags.Model, tags.LensModel);

// Capture settings
console.log(tags.ISO, tags.FNumber, tags.ExposureTime);

// Location (if available)
console.log(tags.GPSLatitude, tags.GPSLongitude);

// Always check for parsing errors
if (tags.errors?.length > 0) {
  console.warn("Metadata warnings:", tags.errors);
}
Copy

Writing Metadata

// Add keywords and copyright
await exiftool.write("photo.jpg", {
  Keywords: ["sunset", "landscape"],
  Copyright: "© 2024 Photographer Name",
  "IPTC:CopyrightNotice": "© 2024 Photographer Name",
});

// Update all date fields at once
await exiftool.write("photo.jpg", {
  AllDates: "2024:03:15 14:30:00",
});

// Delete tags
await exiftool.write("photo.jpg", {
  UserComment: null,
});
Copy

Extracting Images

// Extract thumbnail
await exiftool.extractThumbnail("photo.jpg", "thumbnail.jpg");

// Extract preview (larger than thumbnail)
await exiftool.extractPreview("photo.jpg", "preview.jpg");

// Extract JPEG from RAW files
await exiftool.extractJpgFromRaw("photo.cr2", "processed.jpg");
Copy

Understanding Tags

The Tags interface contains thousands of metadata fields from an auto-generated TypeScript file. Each tag includes semantic JSDoc annotations:

/**
 * @frequency 🔥 ★★★★ (85%)
 * @groups EXIF, MakerNotes
 * @example 100
 */
ISO?: number;

/**
 * @frequency 🧊 ★★★☆ (23%)
 * @groups MakerNotes
 * @example "Custom lens data"
 */
LensSpec?: string;
Copy

• 🔥 = Found on mainstream devices (iPhone, Canon, Nikon, Sony)
• 🧊 = Found on more obscure camera makes and models
• ★★★★ = Found in >50% of files, ☆☆☆☆ = rare (<1%)
• @groups = Metadata categories (EXIF, GPS, IPTC, XMP, etc.)
• @example = Representative values

Important: The interface isn't comprehensive - unknown fields may still exist in returned objects.

📖 Complete Tags Documentation →

Important Notes

⏰ Dates & Timezones

Images rarely specify timezones. This library uses sophisticated heuristics:

1. Explicit metadata (TimeZoneOffset, OffsetTime)
2. GPS location → timezone lookup
3. UTC timestamps → calculate offset

const dt = tags.DateTimeOriginal;
if (dt instanceof ExifDateTime) {
  console.log("Timezone offset:", dt.tzoffset, "minutes");
  console.log("Timezone:", dt.zone);
}
Copy

📖 Date & Timezone Guide →

🧹 Resource Cleanup

Always call .end() on ExifTool instances to prevent Node.js from hanging:

import { exiftool } from "exiftool-vendored";

// Use the singleton
const tags = await exiftool.read("photo.jpg");

// Clean up when done
process.on("beforeExit", () => exiftool.end());
Copy

Automatic Cleanup with Disposable Interfaces

For TypeScript 5.2+ projects, use automatic resource management:

import { ExifTool } from "exiftool-vendored";

// Automatic synchronous cleanup
{
  using et = new ExifTool();
  const tags = await et.read("photo.jpg");
  // ExifTool automatically cleaned up when block exits
}

// Automatic asynchronous cleanup (recommended)
{
  await using et = new ExifTool();
  const tags = await et.read("photo.jpg");
  // ExifTool gracefully cleaned up when block exits
}
Copy

Benefits:

• Guaranteed cleanup: No leaked processes, even with exceptions
• Timeout protection: Automatic forceful cleanup if graceful shutdown hangs
• Zero boilerplate: No manual .end() calls needed

🏷️ Tag Completeness

The Tags interface shows the most common fields, but ExifTool can extract many more. Cast to access unlisted fields:

const tags = await exiftool.read("photo.jpg");
const customField = (tags as any).UncommonTag;
Copy

Documentation

📚 Guides

• Installation Guide - Electron, Docker, platform setup
• Usage Examples - Comprehensive API examples
• Date Handling - Timezone complexities explained
• Tags Reference - Understanding the 2,500+ metadata fields
• Electron Integration - Electron-specific setup

🔧 Troubleshooting

• Debugging Guide - Debug logging and common issues
• Temporal Migration - Future JavaScript Temporal API

📖 API Reference

• TypeDoc Documentation - Complete API reference

Performance

The default singleton is throttled for stability. For high-throughput processing:

import { ExifTool } from "exiftool-vendored";

const exiftool = new ExifTool({
  maxProcs: 8, // More concurrent processes
  minDelayBetweenSpawnMillis: 0, // Faster spawning
  streamFlushMillis: 10, // Faster streaming
});

// Process many files efficiently
const results = await Promise.all(filePaths.map((file) => exiftool.read(file)));

await exiftool.end();
Copy

Benchmarks: 20+ files/second/thread, 500+ files/second using all CPU cores.

Support & Community

• 📋 Issues: GitHub Issues
• 📖 Changelog: CHANGELOG.md
• 🔒 Security: SECURITY.md
• 📄 License: MIT

Contributors 🎉

Matthew McEachen, Joshua Harris, Anton Mokrushin, Luca Ban, Demiurga, David Randler