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.