Class ExifTool

Manages delegating calls to a cluster of ExifTool child processes.

NOTE: Instances are expensive!

use either the default exported singleton instance of this class, exiftool, or your own singleton
make sure you await ExifTool.end when you're done with an instance to clean up subprocesses
review the ExifToolOptions for configuration options--the default values are conservative to avoid overwhelming your system.

See

https://photostructure.github.io/exiftool-vendored.js/ for more documentation.

Index

Constructors

constructor

new ExifTool(options?: Partial<ExifToolOptions>): ExifTool
Parameters
- options: Partial<ExifToolOptions> = {}
Returns ExifTool
- Defined in src/ExifTool.ts:207

Properties

`Readonly`batchCluster

batchCluster: BatchCluster

`Readonly`exiftoolPath

exiftoolPath: () => Promise<string> = ...

`Readonly`off

off: <E extends keyof BatchClusterEvents>(
    eventName: E,
    listener: (
        ...args: BatchClusterEvents[E] extends T
            ? T extends any[any]
                ? T<T> extends (...args: A) => void ? A : never
                : never
            : never,
    ) => void,
) => BatchClusterEmitter = ...

Unregister life cycle event listeners. Delegates to BatchProcess.

Type declaration

- <E extends keyof BatchClusterEvents>(
      eventName: E,
      listener: (
          ...args: BatchClusterEvents[E] extends T
              ? T extends any[any]
                  ? T<T> extends (...args: A) => void ? A : never
                  : never
              : never,
      ) => void,
  ): BatchClusterEmitter
- Type Parameters
  - E extends keyof BatchClusterEvents
  Parameters
  - eventName: E
  - listener: (
        ...args: BatchClusterEvents[E] extends T
            ? T extends any[any]
                ? T<T> extends (...args: A) => void ? A : never
                : never
            : never,
    ) => void
  Returns BatchClusterEmitter
  See
  BatchClusterEvents
  
  Since
  v9.0.0

`Readonly`on

on: <E extends keyof BatchClusterEvents>(
    eventName: E,
    listener: (
        ...args: BatchClusterEvents[E] extends T
            ? T extends any[any]
                ? T<T> extends (...args: A) => void ? A : never
                : never
            : never,
    ) => void,
) => BatchClusterEmitter = ...

Type declaration

- <E extends keyof BatchClusterEvents>(
      eventName: E,
      listener: (
          ...args: BatchClusterEvents[E] extends T
              ? T extends any[any]
                  ? T<T> extends (...args: A) => void ? A : never
                  : never
              : never,
      ) => void,
  ): BatchClusterEmitter
- Type Parameters
  - E extends keyof BatchClusterEvents
  Parameters
  - eventName: E
  - listener: (
        ...args: BatchClusterEvents[E] extends T
            ? T extends any[any]
                ? T<T> extends (...args: A) => void ? A : never
                : never
            : never,
    ) => void
  Returns BatchClusterEmitter
  See
  BatchClusterEvents

`Readonly`options

options: ExifToolOptions

Accessors

busyProcs

get busyProcs(): number
Returns number
the current number of child processes currently servicing tasks
- Defined in src/ExifTool.ts:700

ended

get ended(): boolean
Returns boolean
true if .end() has been invoked
- Defined in src/ExifTool.ts:645

pendingTasks

get pendingTasks(): number
Returns number
the number of pending (not currently worked on) tasks
- Defined in src/ExifTool.ts:686

pids

get pids(): number[]
Returns number[]
the currently running ExifTool processes. Note that on Windows, these are only the process IDs of the directly-spawned ExifTool wrapper, and not the actual perl vm. This should only really be relevant for integration tests that verify processes are cleaned up properly.
- Defined in src/ExifTool.ts:679

spawnedProcs

get spawnedProcs(): number
Returns number
the total number of child processes created by this instance
- Defined in src/ExifTool.ts:693

Methods

childEndCounts

childEndCounts(): {
    broken: number;
    closed: number;
    ended: number;
    ending: number;
    idle: number;
    old: number;
    "proc.close": number;
    "proc.disconnect": number;
    "proc.error": number;
    "proc.exit": number;
    startError: number;
    stderr: number;
    "stderr.error": number;
    "stdin.error": number;
    "stdout.error": number;
    timeout: number;
    tooMany: number;
    unhealthy: number;
    worn: number;
}
Returns {
    broken: number;
    closed: number;
    ended: number;
    ending: number;
    idle: number;
    old: number;
    "proc.close": number;
    "proc.disconnect": number;
    "proc.error": number;
    "proc.exit": number;
    startError: number;
    stderr: number;
    "stderr.error": number;
    "stdin.error": number;
    "stdout.error": number;
    timeout: number;
    tooMany: number;
    unhealthy: number;
    worn: number;
}
report why child processes were recycled
- Defined in src/ExifTool.ts:707

closeChildProcesses

closeChildProcesses(gracefully?: boolean): Promise<void>
Shut down any currently-running child processes. New child processes will be started automatically to handle new tasks.
Parameters
- gracefully: boolean = true
Returns Promise<void>
- Defined in src/ExifTool.ts:715

deleteAllTags

deleteAllTags(
file: string,
opts?: { retain?: string[] } & Partial<ExifToolTaskOptions>,
): Promise<WriteTaskResult>
This will strip file of all metadata tags. The original file (with the name ${FILENAME}_original) will be retained. Note that some tags, like stat information and image dimensions, are intrinsic to the file and will continue to exist if you re-read the file.
Parameters
- file: string
  the file to strip of metadata
- Optionalopts: { retain?: string[] } & Partial<ExifToolTaskOptions>
  - Optionalretain?: string[]
    optional. If provided, this is a list of metadata keys to not delete.
  - retain
    optional. If provided, this is a list of metadata keys to not delete.
Returns Promise<WriteTaskResult>
- Defined in src/ExifTool.ts:468

end

end(gracefully?: boolean): Promise<void>
Shut down running ExifTool child processes. No subsequent requests will be accepted.

This may need to be called in after or finally clauses in tests or scripts for them to exit cleanly.
Parameters
- gracefully: boolean = true
Returns Promise<void>
- Defined in src/ExifTool.ts:638

enqueueTask

enqueueTask<T>(task: () => ExifToolTask<T>, retriable?: boolean): Promise<T>
Most users will not need to use enqueueTask directly. This method supports submitting custom BatchCluster tasks.
Type Parameters
- T
Parameters
- task: () => ExifToolTask<T>
  is a thunk to support retries by providing new instances on retries.
- retriable: boolean = true
Returns Promise<T>
See
BinaryExtractionTask for an example task implementation
- Defined in src/ExifTool.ts:665

extractBinaryTag

extractBinaryTag(
    tagname: string,
    src: string,
    dest: string,
    opts?: BinaryExtractionTaskOptions,
): Promise<void>
Extract a given binary value from "tagname" tag associated to path/to/image.jpg and write it to dest (which cannot exist and whose directory must already exist).
Parameters
- tagname: string
- src: string
- dest: string
- Optionalopts: BinaryExtractionTaskOptions
Returns Promise<void>
a Promise<void>

Throws
if the binary output not be written to dest.
- Defined in src/ExifTool.ts:549

extractBinaryTagToBuffer

extractBinaryTagToBuffer(
    tagname: string,
    imageFile: string,
    opts?: ExifToolTaskOptions,
): Promise<Buffer>
Extract a given binary value from "tagname" tag associated to path/to/image.jpg as a Buffer. This has the advantage of not writing to a file, but if the payload associated to tagname is large, this can cause out-of-memory errors.
Parameters
- tagname: string
- imageFile: string
- Optionalopts: ExifToolTaskOptions
Returns Promise<Buffer>
a Promise<Buffer>

Throws
if the file or tag is missing.
- Defined in src/ExifTool.ts:578

extractJpgFromRaw

extractJpgFromRaw(
    imageFile: string,
    outputFile: string,
    opts?: BinaryExtractionTaskOptions,
): Promise<void>
Extract the "JpgFromRaw" image in path/to/image.jpg and write it to path/to/fromRaw.jpg.

This size of these images varies widely, and is not present in all RAW images. Nikon and Panasonic use this tag.
Parameters
- imageFile: string
- outputFile: string
- Optionalopts: BinaryExtractionTaskOptions
Returns Promise<void>
a Promise<void>

Throws
if the file could not be read or the output not written.
- Defined in src/ExifTool.ts:532

extractPreview

extractPreview(
    imageFile: string,
    previewFile: string,
    opts?: BinaryExtractionTaskOptions,
): Promise<void>
Extract the "preview" image in path/to/image.jpg and write it to path/to/preview.jpg.

The size of these images varies widely, and is present in dSLR images. Canon, Fuji, Olympus, and Sony use this tag.
Parameters
- imageFile: string
- previewFile: string
- Optionalopts: BinaryExtractionTaskOptions
Returns Promise<void>
a Promise<void>

Throws
if the file could not be read or the output not written
- Defined in src/ExifTool.ts:513

extractThumbnail

extractThumbnail(
    imageFile: string,
    thumbnailFile: string,
    opts?: BinaryExtractionTaskOptions,
): Promise<void>
Extract the low-resolution thumbnail in path/to/image.jpg and write it to path/to/thumbnail.jpg.

Note that these images can be less than .1 megapixels in size.
Parameters
- imageFile: string
- thumbnailFile: string
- Optionalopts: BinaryExtractionTaskOptions
Returns Promise<void>
a Promise<void>

Throws
if the file could not be read or the output not written
- Defined in src/ExifTool.ts:489

read

read<T extends Tags = Tags>(
    file: string,
    options?: Partial<
        {
            adjustTimeZoneIfDaylightSavings: (
                tags: Tags,
                tz: string,
            ) => Maybe<number>;
            backfillTimezones: boolean;
            defaultVideosToUTC: boolean;
            geolocation: boolean;
            geoTz: (lat: number, lon: number) => Maybe<string>;
            ignoreMinorErrors: boolean;
            ignoreZeroZeroLatLon: boolean;
            imageHashType: false | "MD5" | "SHA256" | "SHA512";
            includeImageDataMD5: undefined | boolean;
            inferTimezoneFromDatestamps: boolean;
            inferTimezoneFromDatestampTags: (keyof Tags)[];
            inferTimezoneFromTimeStamp: boolean;
            numericTags: string[];
            preferTimezoneInferenceFromGps: boolean;
            readArgs: string[];
            struct: 0 | 1 | 2 | "undef";
            useMWG: boolean;
        },
    >,
): Promise<T>
Read the tags in file.
Type Parameters
- T extends Tags = Tags
Parameters
- file: string
  the file to extract metadata tags from
- Optionaloptions: Partial<
      {
          adjustTimeZoneIfDaylightSavings: (
              tags: Tags,
              tz: string,
          ) => Maybe<number>;
          backfillTimezones: boolean;
          defaultVideosToUTC: boolean;
          geolocation: boolean;
          geoTz: (lat: number, lon: number) => Maybe<string>;
          ignoreMinorErrors: boolean;
          ignoreZeroZeroLatLon: boolean;
          imageHashType: false | "MD5" | "SHA256" | "SHA512";
          includeImageDataMD5: undefined | boolean;
          inferTimezoneFromDatestamps: boolean;
          inferTimezoneFromDatestampTags: (keyof Tags)[];
          inferTimezoneFromTimeStamp: boolean;
          numericTags: string[];
          preferTimezoneInferenceFromGps: boolean;
          readArgs: string[];
          struct: 0 | 1 | 2 | "undef";
          useMWG: boolean;
      },
  >
  overrides to the default ExifTool options provided to the ExifTool constructor.
Returns Promise<T>
A resolved Tags promise. If there are errors during reading, the .errors field will be present.
- Defined in src/ExifTool.ts:286
read<T extends Tags = Tags>(
    file: string,
    readArgs?: string[],
    options?: Partial<
        {
            adjustTimeZoneIfDaylightSavings: (
                tags: Tags,
                tz: string,
            ) => Maybe<number>;
            backfillTimezones: boolean;
            defaultVideosToUTC: boolean;
            geolocation: boolean;
            geoTz: (lat: number, lon: number) => Maybe<string>;
            ignoreMinorErrors: boolean;
            ignoreZeroZeroLatLon: boolean;
            imageHashType: false | "MD5" | "SHA256" | "SHA512";
            includeImageDataMD5: undefined | boolean;
            inferTimezoneFromDatestamps: boolean;
            inferTimezoneFromDatestampTags: (keyof Tags)[];
            inferTimezoneFromTimeStamp: boolean;
            numericTags: string[];
            preferTimezoneInferenceFromGps: boolean;
            readArgs: string[];
            struct: 0 | 1 | 2 | "undef";
            useMWG: boolean;
        },
    >,
): Promise<T>
Read the tags in file.
Type Parameters
- T extends Tags = Tags
Parameters
- file: string
  the file to extract metadata tags from
- OptionalreadArgs: string[]
  any additional ExifTool arguments, like ["-fast"], ["-fast2"], ["-g"], or ["-api", "largefilesupport=1"]. Note that providing a value here will override the readArgs array provided to the ExifTool constructor. Note that most other arguments will require you to use readRaw. Note that the default is ["-fast"], so if you want ExifTool to read the entire file for metadata, you should pass an empty array as the second parameter. See https://exiftool.org/#performance for more information about -fast and -fast2.
- Optionaloptions: Partial<
      {
          adjustTimeZoneIfDaylightSavings: (
              tags: Tags,
              tz: string,
          ) => Maybe<number>;
          backfillTimezones: boolean;
          defaultVideosToUTC: boolean;
          geolocation: boolean;
          geoTz: (lat: number, lon: number) => Maybe<string>;
          ignoreMinorErrors: boolean;
          ignoreZeroZeroLatLon: boolean;
          imageHashType: false | "MD5" | "SHA256" | "SHA512";
          includeImageDataMD5: undefined | boolean;
          inferTimezoneFromDatestamps: boolean;
          inferTimezoneFromDatestampTags: (keyof Tags)[];
          inferTimezoneFromTimeStamp: boolean;
          numericTags: string[];
          preferTimezoneInferenceFromGps: boolean;
          readArgs: string[];
          struct: 0 | 1 | 2 | "undef";
          useMWG: boolean;
      },
  >
  overrides to the default ExifTool options provided to the ExifTool constructor.
Returns Promise<T>
A resolved Tags promise. If there are errors during reading, the .errors field will be present.

Deprecated
use (file: string, options?: ReadTaskOptions) instead (move readArgs into your options hash)
- Defined in src/ExifTool.ts:315

readRaw

readRaw(file: string, args?: string[]): Promise<RawTags>
Read the tags from file, without any post-processing of ExifTool values.

You probably want read, not this method. READ THE REST OF THIS COMMENT CAREFULLY.

If you want to extract specific tag values from a file, you may want to use this, but all data validation and inference heuristics provided by read will be skipped.

Note that performance will be very similar to read, and will actually be worse if you don't include -fast or -fast2 (as the most expensive bit is the perl interpreter and scanning the file on disk).
Parameters
- file: string
- args: string[] = []
  any additional arguments other than the file path. Note that "-json", and the Windows unicode filename handler flags, "-charset filename=utf8", will be added automatically.
Returns Promise<RawTags>
Note that the return value will be similar to Tags, but with no date, time, or other rich type parsing that you get from .read(). The field values will be string | number | string[].

See
https://github.com/photostructure/exiftool-vendored.js/issues/44 for typing details.
- Defined in src/ExifTool.ts:360

rewriteAllTags

rewriteAllTags(
    inputFile: string,
    outputFile: string,
    opts?: { allowMakerNoteRepair?: boolean } & ExifToolTaskOptions,
): Promise<void>
Attempt to fix metadata problems in JPEG images by deleting all metadata and rebuilding from scratch. After repairing an image you should be able to write to it without errors, but some metadata from the original image may be lost in the process.

This should only be applied as a last resort to images whose metadata is not readable via ().
Parameters
- inputFile: string
  the path to the problematic image
- outputFile: string
  the path to write the repaired image
- Optionalopts: { allowMakerNoteRepair?: boolean } & ExifToolTaskOptions
  - OptionalallowMakerNoteRepair?: boolean
    if there are problems with MakerNote tags, allow ExifTool to apply heuristics to recover corrupt tags. See exiftool's -F flag.
Returns Promise<void>
resolved after the outputFile has been written.

See
https://exiftool.org/faq.html#Q20
- Defined in src/ExifTool.ts:617

version

version(): Promise<string>
Returns Promise<string>
a promise holding the version number of the vendored ExifTool
- Defined in src/ExifTool.ts:271

write

write(
    file: string,
    tags: WriteTags,
    options?: Partial<
        {
            ignoreMinorErrors: boolean;
            struct: 0
            | 1
            | 2
            | "undef";
            useMWG: boolean;
            writeArgs: string[];
        },
    >,
): Promise<WriteTaskResult>
Write the given tags to file.
Parameters
- file: string
  an existing file to write tags to
- tags: WriteTags
  the tags to write to file
- Optionaloptions: Partial<
      {
          ignoreMinorErrors: boolean;
          struct: 0
          | 1
          | 2
          | "undef";
          useMWG: boolean;
          writeArgs: string[];
      },
  >
  overrides to the default ExifTool options provided to the ExifTool constructor.
Returns Promise<WriteTaskResult>
Either the promise will be resolved if the tags are written to successfully, or the promise will be rejected if there are errors or warnings.

See
https://exiftool.org/exiftool_pod.html#overwrite_original
- Defined in src/ExifTool.ts:382
write(
    file: string,
    tags: WriteTags,
    writeArgs?: string[],
    options?: Partial<
        {
            ignoreMinorErrors: boolean;
            struct: 0
            | 1
            | 2
            | "undef";
            useMWG: boolean;
            writeArgs: string[];
        },
    >,
): Promise<WriteTaskResult>
Parameters
- file: string
  an existing file to write tags to
- tags: WriteTags
  the tags to write to file.
- OptionalwriteArgs: string[]
  any additional ExifTool arguments, like -n, or -overwrite_original.
- Optionaloptions: Partial<
      {
          ignoreMinorErrors: boolean;
          struct: 0
          | 1
          | 2
          | "undef";
          useMWG: boolean;
          writeArgs: string[];
      },
  >
  overrides to the default ExifTool options provided to the ExifTool constructor.
Returns Promise<WriteTaskResult>
Either the promise will be resolved if the tags are written to successfully, or the promise will be rejected if there are errors or warnings.

See
https://exiftool.org/exiftool_pod.html#overwrite_original

Deprecated
use (file: string, tags: WriteTags, options?: WriteTaskOptions) instead: move writeArgs into your options hash.
- Defined in src/ExifTool.ts:409

Class ExifTool

See

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns ExifTool

Properties

ReadonlybatchCluster

ReadonlyexiftoolPath

Readonlyoff

Type declaration

Type Parameters

Parameters

Returns BatchClusterEmitter

See

Since

Readonlyon

Type declaration

Type Parameters

Parameters

Returns BatchClusterEmitter

See

Readonlyoptions

Accessors

busyProcs

Returns number

ended

Returns boolean

pendingTasks

Returns number

pids

Returns number[]

spawnedProcs

Returns number

Methods

childEndCounts

closeChildProcesses

Parameters

Returns Promise<void>

deleteAllTags

Parameters

Optionalretain?: string[]

retain

Returns Promise<WriteTaskResult>

end

Parameters

Returns Promise<void>

enqueueTask

Type Parameters

Parameters

Returns Promise<T>

See

extractBinaryTag

Parameters

Returns Promise<void>

Throws

extractBinaryTagToBuffer

Parameters

Returns Promise<Buffer>

Throws

extractJpgFromRaw

Parameters

Returns Promise<void>

Throws

extractPreview

Parameters

Returns Promise<void>

Throws

extractThumbnail

Parameters

Returns Promise<void>

Throws

read

Type Parameters

Parameters

`Readonly`batchCluster

`Readonly`exiftoolPath

`Readonly`off

`Readonly`on

`Readonly`options

`Optional`retain?: string[]

`Optional`allowMakerNoteRepair?: boolean