• Public
  • Public/Protected
  • All

Interface ExifToolOptions


  • BatchClusterOptions
  • BatchProcessOptions
  • ChildProcessFactory
    • ExifToolOptions



cleanupChildProcs: boolean

Should batch-cluster try to clean up after spawned processes that don't shut down?

Only disable this if you have another means of PID cleanup.

Defaults to true.

endGracefulWaitTimeMillis: number

When this.end() is called, or Node broadcasts the beforeExit event, this is the milliseconds spent waiting for currently running tasks to finish before sending kill signals to child processes.

Setting this value to 0 means child processes will immediately receive a kill signal to shut down. Any pending requests may be interrupted. Must be >= 0. Defaults to 500ms.

exiftoolArgs: string[]

Args passed to exiftool on launch.

exiftoolEnv: ProcessEnv

Environment variables passed to ExifTool (besides EXIFTOOL_HOME)

exiftoolPath: string

Allows for non-standard paths to ExifTool. Defaults to the perl or windows binaries provided by exiftool-vendored.pl or exiftool-vendored.exe.

exitCommand?: string

Command to end the child batch process. If not provided (or undefined), stdin will be closed to signal to the child process that it may terminate, and if it does not shut down within endGracefulWaitTimeMillis, it will be SIGHUP'ed.

fail: string | RegExp

Expected text to print if a command fails. Cannot be blank. Strings will be interpreted as a regular expression fragment.

healthCheckCommand?: string

If provided, and healthCheckIntervalMillis is greater than 0, this command will be sent to child processes.

If the command outputs to stderr or returns a fail string, the process will be considered unhealthy and recycled.

healthCheckIntervalMillis: number

If healthCheckCommand is set, how frequently should we check for unhealthy child processes?

Set this to 0 to disable this feature.

ignoreShebang: boolean

ExifTool has a shebang line that assumes a valid perl is installed at /usr/bin/perl.

Some environments may not include a valid /usr/bin/perl (like AWS Lambda), but perl may be available in your PATH some place else (like /opt/bin/perl), if you pull in a perl layer.

This will default to true in those environments as a workaround in these situations. Note also that perl will be spawned in a sub-shell.

logger: () => Logger

Type declaration

    • (): Logger
    • A BatchCluster instance and associated BatchProcess instances will share this Logger. Defaults to the Logger instance provided to setLogger().

      Returns Logger

maxFailedTasksPerProcess: number

How many failed tasks should a process be allowed to process before it is recycled?

Set this to 0 to disable this feature.

maxIdleMsPerProcess: number

If a child process is idle for more than this value (in milliseconds), shut it down to reduce system resource consumption.

A value of ~10 seconds to a couple minutes would be reasonable. Set this to 0 to disable this feature.

maxProcAgeMillis: number

Child processes will be recycled when they reach this age.

If this value is set to 0, child processes will not "age out".

This value must not be less than spawnTimeoutMillis or taskTimeoutMillis.

Defaults to 5 minutes.

maxProcs: number

The maximum number of ExifTool child processes to spawn when load merits.

Defaults to 1/4 the number of CPUs, minimally 1.

maxReasonableProcessFailuresPerMinute: number

If the initial versionCommand fails for new spawned processes more than this rate, end this BatchCluster and throw an error, because something is terribly wrong.

If this backstop didn't exist, new (failing) child processes would be created indefinitely.

Must be >= 0. Defaults to 10.

maxTasksPerProcess: number

The maximum number of requests a given ExifTool process will service before being retired.

Defaults to 500, to balance performance with memory usage.

minDelayBetweenSpawnMillis: number

If maxProcs > 1, spawning new child processes to process tasks can slow down initial processing, and create unnecessary processes.

Must be >= 0ms. Defaults to 1.5 seconds.

numericTags: string[]

Tag names (which can have '*' glob matchers) which you want numeric values, rather than ExifTool's "Print Conversion."

If the tag value is only for human consumption, you may want to leave this blank. The default is ["*Duration*"], but you may want to include "Orientation" as well.

onIdleIntervalMillis: number

An interval timer is scheduled to do periodic maintenance of underlying child processes with this periodicity.

Defaults to 2 seconds.

pass: string | RegExp

Expected text to print if a command passes. Cannot be blank. Strings will be interpreted as a regular expression fragment.

pidCheckIntervalMillis: number

Verify child processes are still running by checking the OS process table.

Set this to 0 to disable this feature.

spawnTimeoutMillis: number

Spawning new ExifTool processes must not take longer than spawnTimeoutMillis millis before it times out and a new attempt is made. Be pessimistic here--windows can regularly take several seconds to spin up a process, thanks to antivirus shenanigans. This can't be set to a value less than 100ms.

Defaults to 30 seconds, to accommodate slow Windows machines.

streamFlushMillis: number

When a task sees a "pass" or "fail" from either stdout or stderr, it needs to wait for the other stream to finish flushing to ensure the task's Parser sees the entire relevant stream contents. A larger number may be required for slower computers to prevent internal errors due to lack of stream coercion.

Note that this puts a hard lower limit on task latency. You don't want to set this to a large number, and you'll potentially miss errors if you set this to low.

Defaults to 10ms on Linux and 100ms on macOS and Windows due to slow stream handling.

taskRetries: number

The number of times a task can error or timeout and be retried.

Defaults to 1 (every task gets 2 chances).

taskTimeoutMillis: number

If requests to ExifTool take longer than this, presume the underlying process is dead and we should restart the task. This can't be set to a value less than 10ms, and really should be set to at more than a second unless taskRetries is sufficiently large or all writes will be to a fast local disk. Defaults to 10 seconds.

versionCommand: string

Low-overhead command to verify the child batch process has started. Will be invoked immediately after spawn. This command must return before any tasks will be given to a given process.


  • processFactory(): ChildProcess | Promise<ChildProcess>
  • Expected to be a simple call to execFile. Platform-specific code is the responsibility of this thunk. Error handlers will be registered as appropriate.

    Returns ChildProcess | Promise<ChildProcess>

Generated using TypeDoc