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.

Constructors

constructor

Properties

batchCluster exiftoolPath off on options

Accessors

busyProcs ended pendingTasks pids spawnedProcs

Methods

childEndCounts closeChildProcesses deleteAllTags end enqueueTask extractBinaryTag extractBinaryTagToBuffer extractJpgFromRaw extractPreview extractThumbnail read readRaw rewriteAllTags version write

Constructors

constructor

Properties

ReadonlybatchCluster

batchCluster: BatchCluster

ReadonlyexiftoolPath

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

Readonlyoff

off: (<E>(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>(eventName, listener): 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)
          • (...args): void

          • Parameters

            • Rest...args: BatchClusterEvents[E] extends T
                  ? T extends any[any]
                      ? T<T> extends ((...args: A) => void)
                          ? A
                          : never
                      : never
                  : never

            Returns void

      Returns BatchClusterEmitter

      See

      BatchClusterEvents

      Since

      v9.0.0

Readonlyon

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

Register life cycle event listeners. Delegates to BatchProcess.

Type declaration

    • <E>(eventName, listener): 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)
          • (...args): void

          • Parameters

            • Rest...args: BatchClusterEvents[E] extends T
                  ? T extends any[any]
                      ? T<T> extends ((...args: A) => void)
                          ? A
                          : never
                      : never
                  : never

            Returns void

      Returns BatchClusterEmitter

      See

      BatchClusterEvents

Readonlyoptions

options: ExifToolOptions

Accessors

busyProcs

ended

pendingTasks

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.

spawnedProcs

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

    • 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

closeChildProcesses

  • closeChildProcesses(gracefully?): 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>

deleteAllTags

  • deleteAllTags(file, opts?): 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>

    Returns Promise<WriteTaskResult>

end

  • end(gracefully?): 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>

enqueueTask

  • enqueueTask<T>(task, retriable?): Promise<T>

  • Most users will not need to use enqueueTask directly. This method supports submitting custom BatchCluster tasks.

    Type Parameters

    • T

    Parameters

    Returns Promise<T>

    See

    BinaryExtractionTask for an example task implementation

extractBinaryTag

  • extractBinaryTag(tagname, src, dest, opts?): 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

    Returns Promise<void>

    a Promise<void>. The promise will be rejected if the binary output not be written to dest.

extractBinaryTagToBuffer

  • extractBinaryTagToBuffer(tagname, imageFile, opts?): 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

    Returns Promise<Buffer>

    a Promise<Buffer>. The promise will be rejected if the file or tag is missing.

extractJpgFromRaw

  • extractJpgFromRaw(imageFile, outputFile, opts?): 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

    Returns Promise<void>

    a Promise<void>. The promise will be rejected if the file could not be read or the output not written.

extractPreview

  • extractPreview(imageFile, previewFile, opts?): 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

    Returns Promise<void>

    a Promise<void>. An Error is raised if the file could not be read or the output not written.

extractThumbnail

  • extractThumbnail(imageFile, thumbnailFile, opts?): 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

    Returns Promise<void>

    a Promise<void>. An Error is raised if the file could not be read or the output not written.

read

  • read<T>(file, options?): Promise<T>

  • Read the tags in file.

    Type Parameters

    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.

  • read<T>(file, readArgs?, options?): Promise<T>

  • Read the tags in file.

    Type Parameters

    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)

readRaw

  • readRaw(file, args?): 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.

rewriteAllTags

  • rewriteAllTags(inputFile, outputFile, opts?): 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

    Returns Promise<void>

    resolved when outputFile has been written.

    See

    https://exiftool.org/faq.html#Q20

version

write

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods