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

Name	Transformer Markup	Description	Example(s) Output
Year	YYYY	Date based numeric year.	2018
Month	DD	Date based numeric day of the month.	1, 10, 20, 30
	DD0	Date based numeric day of the month with leading zero.	01, 10, 20, 30
	MM	Date based month numeric month of the year.	1, 4, 5, 12
	MM0	Date based month numeric month of the year with leading zero.	01, 04, 05, 12
	Month	Date based name of month.	January
	lcMonth	Date based lowercase name of month.	january
	ucMonth	Date based uppercase name of month.	JANUARY
Week	Day	Date based day of the week.	Sunday
	lcDay	Date based lowercase day of the week.	sunday
	ucDay	Date based uppercase day of the week.	SUNDAY

Time based

Name	Transformer Markup	Description	Example(s) Output
Hour	HH	Time based numeric hour media was captured.	0, 9, 12, 23
	HH0	Time based numeric hour media was captured with leading zero.	00, 09, 12, 23
Minute	MN	Time based numeric minute media was captured.	0, 7, 31, 44, 59
	MN0	Time based numeric minute media was captured with leading zero.	00, 07, 31, 44, 59

Device Based

Name	Transformer Markup	Description	Example(s) Output
Device Make	Make	Make of camera used from media metadata.	Sony
	lcMake	Lowercase make of camera used from media metadata.	sony
	ucMake	Uppercase make of camera used from media metadata.	SONY
Device Model	Model	Model of camera used from media metadata.	Nexus 5x
	lcModel	Lowercase model of camera used from media metadata.	nexus 5x
	ucModel	Uppercase model of camera used from media metadata.	NEXUS 5X

File Metadata Based

Name	Transformer Markup	Description	Example(s) Output
Extension	Ext	Original file extension of source file.	Jpeg
	lcExt	Lowercase File Extension of source file.	jpeg
	ucExt	Uppercase File Extension of source file.	JPEG
Height	Height	Pixel height of media.	1080
Orientation	Orientation	Orientation of camera when photo was taken.	Horizontal (normal)
	lcOrientation	Lowercase orientation of camera when photo was taken.	horizontal (normal)
	ucOrientation	Uppercase orientation of camera when photo was taken.	HORIZONTAL (NORMAL)
Width	Width	Pixel width of media.	1920

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.