Remediator

Node library to sort images and video based off of their filesystem metadata or exif/media metadata formatted from a predefined or custom template.

Installation

Installation assumes you have already installed v8.5.0 or greater of Node.js. If you have not done this, or do not know how to, please follow the directions at https://nodejs.org/.

Setup Application

Either use an existing npm package or follow these steps to create a new application.

$ mkdir myNewApp
$ cd myNewApp
$ npm init

Get Remediator

Now install the Remediator and exiftool-vendored packages into your application and save them as dependencies.

$ npm install exiftool-vendored remediator --save

Usage

Remediator is a simple to use library that accepts a single options object for its arguments. Remediator returns a Promise that resolves successful file transformation objects and rejects any errors encountered.

Basic Example

Assuming you have a directory named /unsorted that contains a single file named image.jpg that was taken at 1:00 AM on January 1st, 2000. The following code could be used to sort the directory using default options settings.

import { exiftool } from 'exiftool-vendored';
import remediator from 'remediator';

async function example() {
  const results = await remediator({
    exiftool,
    source: [
      '/unsorted',
    ],
    output: '/sorted',
  });
  
  console.log(results);
}

Note: In order for Exiftool to have the proper permissions a reference must be provided to remediator. Note: First run of remediator may take slightly longer as "exiftool-vendored" will need to download the Exiftool process for the given environment.

Since the we are using the default format of :YYYY:/:MM0:. :Month:/:DD0: :Day:/:YYYY:.:MM0:.:DD0: :HH0:.:MN0:.:Ext: the expected output from the above code would be:

[
  {
    source: '/unsorted/image.jpg',
    output: '/sorted/2000/01. January/01 Saturday/2000.01.01 01.00.jpg',
  },
]

Note: If skipErrors option is true if any errors were encountered for a source a error key will be present with the error preventing transformation.

Finally, since this was using the default mode of "dry" /unsorted/image.jpg should remain and /sorted/2000/01. January/01 Saturday/2000.01.01 01.00.jpg should not exist.

Remediator Options

Batch Size

Description: Amount of files to process asynchronously at a time. Key: batchSize Type: Integer Required: No Default: 20

Exiftool

Description: Reference to the Exiftool process object from "exiftool-vendored". "exiftool-vendored" will determine the appropriate exiftool binary to install and be used by Remediator. See usage in basic example above. Key: exiftool Type: Object Required: Yes

Format

Description: Template string to use when building new file names. Key: format Type: String Required: No Default: :YYYY:/:MM0:. :Month:/:DD0: :Day:/:YYYY:.:MM0:.:DD0: :HH0:.:MN0:.:Ext:

Mode

Description: Remediator supports running in 3 different modes: dry, copy, or move.

• Dry - Remediator resolves only the results without actually changing any files.
• Copy - Remediator resolves results and copies files to new paths.
• Move - Remeditaor resolves results and moves original files to new paths.

Key: mode Type: string Required: No Default: dry

Output directory

Description: Base output directory for transformed files. Must have read and write permissions to this directory. Key: output Type: String Required: Yes

Recurse Source Directories

Description: Whether or not to get all files from subdirectories of source directories. Key: recursive Type: Boolean Required: No Default: false

Skip Processing Errors

Description: If you would like to not throw or reject errors during processing you may choose to skip errors. Skipping errors allows to continue process all files in source directories even if an error is encountered along the way. If errors are skipped then the final results will include an array of errors that were encountered. Key: skipErrors Type: Boolean Required: No Default: false

Source Directories

Description: Directory(s) to get files to transform from. Source may be a single directory as a string or as an array of directory strings. Key: source Type: String|Array Required: Yes

Building Format Strings

Format strings are simply a basic template for file output. :'s are used to denote the start and end of a transformer section. Remediator will replace the first "transformer" it encounters in a section. If the first transformer found is empty or null everything between the :'s will not be added to the filename.

For example, if you have a format string of :YYYY::-Make-:.:Ext: and a image named image.jpg that was taken in the year 2000 but does NOT have any exif data for the device make the output would be: 2000.jpg. However, if image.jpg did have a device make of "Sony" the output would be: 2000-Sony-.jpg.

The following tables list all currently supported "transformers" by Remediator.

Transformers

Date based

Time based

Device Based

File Metadata Based

Acknowledgements

Remediator would not be possible without Exiftool by Phil Harvey. Please consider donating!

Additionally, big thanks to Adobe Systems for allowing work on the original prototype of Remediator during a Hackathon.