132 lines
4.2 KiB
Markdown
132 lines
4.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
This is exiftool-vendored.js, a Node.js library that provides cross-platform access to ExifTool for reading and writing metadata in photos and videos. The library includes comprehensive TypeScript type definitions for metadata tags and is used by PhotoStructure and 500+ other projects.
|
|
|
|
## Key Commands
|
|
|
|
### Building & Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Compile TypeScript to JavaScript
|
|
npm run compile
|
|
|
|
# Watch mode for development
|
|
npm run compile:watch
|
|
|
|
# Clean build artifacts
|
|
npm run clean
|
|
```
|
|
|
|
### Linting & Formatting
|
|
|
|
```bash
|
|
# Run ESLint with TypeScript configuration
|
|
npm run lint
|
|
|
|
# Format all TypeScript and other files with Prettier
|
|
npm run fmt
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests (requires compilation first)
|
|
npm test
|
|
|
|
# Note: Tests use Mocha and execute the compiled JavaScript files in dist/
|
|
```
|
|
|
|
### Documentation
|
|
|
|
```bash
|
|
# Generate TypeDoc documentation
|
|
npm run docs
|
|
|
|
# This runs the typedoc tool and serves the documentation locally
|
|
```
|
|
|
|
### Tag Generation
|
|
|
|
```bash
|
|
# Regenerate src/Tags.ts from sample images
|
|
npm run mktags ../path/to/images
|
|
|
|
# This requires a directory of sample images to analyze and extract metadata tags
|
|
```
|
|
|
|
## Architecture & Key Concepts
|
|
|
|
### Core Components
|
|
|
|
1. **ExifTool Class** (`src/ExifTool.ts`): Main entry point that wraps ExifTool process management using batch-cluster. Provides methods for reading metadata, writing tags, extracting binaries, and rewriting tags.
|
|
|
|
2. **Tags Interface** (`src/Tags.ts`): Auto-generated TypeScript interface containing ~2000 metadata fields commonly found in photo/video files. Generated by analyzing thousands of sample files to avoid TypeScript union type limits. Fields include popularity ratings and example values.
|
|
|
|
3. **Date/Time Handling**: Custom classes for handling EXIF dates with timezone complexities:
|
|
|
|
- `ExifDate`: Date without time
|
|
- `ExifTime`: Time without date
|
|
- `ExifDateTime`: Date and time with optional timezone
|
|
|
|
4. **Task System**: Various task classes for different operations:
|
|
|
|
- `ReadTask`: Read metadata from files
|
|
- `WriteTask`: Write metadata to files
|
|
- `BinaryExtractionTask`: Extract thumbnails/previews
|
|
- `RewriteAllTagsTask`: Repair corrupt metadata
|
|
|
|
5. **Platform Support**: Includes platform-specific ExifTool binaries via optional dependencies:
|
|
- `exiftool-vendored.exe` for Windows
|
|
- `exiftool-vendored.pl` for Unix-like systems
|
|
|
|
### Timezone Handling
|
|
|
|
The library implements sophisticated timezone heuristics to handle underspecified date metadata:
|
|
|
|
1. Uses explicit timezone metadata if available
|
|
2. Falls back to GPS location for timezone inference
|
|
3. Uses UTC timestamp deltas to infer timezone offsets
|
|
4. Handles edge cases like daylight saving time transitions
|
|
|
|
### Tag Generation Process
|
|
|
|
The `mktags.ts` script analyzes sample images to generate TypeScript interfaces:
|
|
|
|
1. Scans image directories for various formats (JPEG, RAW, video)
|
|
2. Extracts metadata using ExifTool
|
|
3. Counts tag frequencies and value types
|
|
4. Generates strongly-typed interfaces for the most common ~2000 tags
|
|
5. Includes popularity ratings (★★★★ = >50% of samples)
|
|
|
|
### Testing Approach
|
|
|
|
Tests use Mocha with Chai assertions:
|
|
|
|
- Unit tests for individual components (dates, parsers, etc.)
|
|
- Integration tests for ExifTool operations
|
|
- Test images in the `test/` directory cover various edge cases
|
|
- Includes non-English filename tests
|
|
|
|
## Important Notes
|
|
|
|
- Always run `npm run compile` before testing
|
|
- The singleton `exiftool` instance must be properly ended with `.end()` to clean up child processes
|
|
- Tag interfaces are not comprehensive - less common tags may exist in returned objects
|
|
- The library uses batch processing for performance, managing process pools automatically
|
|
- TypeScript's union type limits require careful tag selection to avoid compilation errors
|
|
|
|
## Important TypeScript Hygiene
|
|
|
|
- You MUST use `if (x != null)` to test for `null` or `undefined` values.
|
|
DO NOT use `if (x)`: this is problematic (especially when handling boolean values).
|
|
|
|
- You MUST use `??` for nullish coalescing.
|
|
DO NOT use `||`: this is problematic (especially when handling boolean values).
|