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

1npm install exiftool-vendored

1import { exiftool } from "exiftool-vendored";
2
3// Read metadata
4const tags = await exiftool.read("photo.jpg");
5console.log(`Camera: ${tags.Make} ${tags.Model}`);
6console.log(`Taken: ${tags.DateTimeOriginal}`);
7console.log(`Size: ${tags.ImageWidth}x${tags.ImageHeight}`);
8
9// Write metadata
10await exiftool.write("photo.jpg", {
11  XPComment: "Amazing sunset!",
12  Copyright: "© 2024 Your Name",
13});
14
15// Extract thumbnail
16await exiftool.extractThumbnail("photo.jpg", "thumb.jpg");
17
18// The singleton instance automatically cleans up on process exit by default.
19// If you need immediate cleanup or have disabled registerExitHandlers:
20// await exiftool.end();

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

1const tags = await exiftool.read("photo.jpg");
2
3// Camera info
4console.log(tags.Make, tags.Model, tags.LensModel);
5
6// Capture settings
7console.log(tags.ISO, tags.FNumber, tags.ExposureTime);
8
9// Location (if available)
10console.log(tags.GPSLatitude, tags.GPSLongitude);
11
12// Always check for parsing errors
13if (tags.errors?.length > 0) {
14  console.warn("Metadata warnings:", tags.errors);
15}

Writing Metadata

1// Add keywords and copyright
2await exiftool.write("photo.jpg", {
3  Keywords: ["sunset", "landscape"],
4  Copyright: "© 2024 Photographer Name",
5  "IPTC:CopyrightNotice": "© 2024 Photographer Name",
6});
7
8// Update all date fields at once
9await exiftool.write("photo.jpg", {
10  AllDates: "2024:03:15 14:30:00",
11});
12
13// Delete tags
14await exiftool.write("photo.jpg", {
15  UserComment: null,
16});

Extracting Images

1// Extract thumbnail
2await exiftool.extractThumbnail("photo.jpg", "thumbnail.jpg");
3
4// Extract preview (larger than thumbnail)
5await exiftool.extractPreview("photo.jpg", "preview.jpg");
6
7// Extract JPEG from RAW files
8await exiftool.extractJpgFromRaw("photo.cr2", "processed.jpg");

Understanding Tags

The Tags interface contains thousands of metadata fields from an auto-generated TypeScript file. Each tag uses a special notation:

1/** ★★★★ ✔ Example: 1920 */
2ImageWidth?: number;        // Very common, all cameras
3
4/** ★☆☆☆   Example: "Custom" */
5RareTag?: string;          // Rare, <1% of files

• ★★★★ = Found in >50% of files (very common)
• ★☆☆☆ = Very rare, <1% of files
• ✔ = Found in popular cameras (Canon, Nikon, Sony, Apple)

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

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

📖 Date & Timezone Guide →

🧹 Resource Cleanup

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

1import { exiftool } from "exiftool-vendored";
2
3// Use the singleton
4const tags = await exiftool.read("photo.jpg");
5
6// Clean up when done
7process.on("beforeExit", () => exiftool.end());

Automatic Cleanup with Disposable Interfaces

For TypeScript 5.2+ projects, use automatic resource management:

1import { ExifTool } from "exiftool-vendored";
2
3// Automatic synchronous cleanup
4{
5  using et = new ExifTool();
6  const tags = await et.read("photo.jpg");
7  // ExifTool automatically cleaned up when block exits
8}
9
10// Automatic asynchronous cleanup (recommended)
11{
12  await using et = new ExifTool();
13  const tags = await et.read("photo.jpg");
14  // ExifTool gracefully cleaned up when block exits
15}

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:

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

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:

1import { ExifTool } from "exiftool-vendored";
2
3const exiftool = new ExifTool({
4  maxProcs: 8, // More concurrent processes
5  minDelayBetweenSpawnMillis: 0, // Faster spawning
6  streamFlushMillis: 10, // Faster streaming
7});
8
9// Process many files efficiently
10const results = await Promise.all(filePaths.map((file) => exiftool.read(file)));
11
12await exiftool.end();

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