exif-assistant

CLI tool providing commands that read, write and edit images EXIF metadata. It processes entire directory trees, helping to detect and fill missing or wrong EXIF info in photos collections with a single command.

Installation

This module should be installed globally using NPM

npm install -g exif-assistant

Once installed, you can use the exif-assistant CLI command to run any of the available module commands:

exif-assistant set-dates ./photos

Note: You can also use npx to use the module without installing it: npx exif-assistant set-dates ./photos

Use cases

This package has been created to meet a specific requirement of the author: He owns a large collection of photos, and it contained lots of old files that didn't have any EXIF information. But files contained date information in their names, or in folder names. So, this program is mainly focused on filling EXIF dates based on file names or folder names recursively to an entire photos collection with a single command. Who knows, maybe it can be also useful for you 😃

For the moment, set-dates is the only one command available. But, the package has been developed in a way that more commands can be added in the future to provide similar features easily, such as adding GPS information, renaming or moving files based on EXIF info, removing EXIF info, etc. Feel free to open issues if you have any suggestion about more features that may be useful.

Commands

set-dates

Sets DateTimeOriginal Exif property to all supported images in a folder recursively. It can determine the date to be set to a specific file based on the file name, parent folder names, other Exif properties or user options. It can modify original files or create another output folder, in which it is able to copy even unsupported files, so you can get a whole copy of the folder, but with Exif dates modified when possible. As an extra, it can create subfolders on each folder tree and move files without date there after finishing, so you can easily examine the images to manually rename files or folders and run again the command only on those folders.

exif-assistant set-dates ./photos --dateFormat dd-MM --dateFormat yyyy --dateRegex "^date-(\S*)" --baseDate 2022

How does it work

The default priority for determining the date to be set into a file is the next one, but it can be modified using the command options:

• Date from the date option, if defined.
• Date found in the file name.
• Date found in the parent folder. Searches recursively in parent folders until the input folder.
• Date from the dateFallback option.
• Date from the DateTimeDigitized exif info, only in case DateTimeOriginal is empty.

Dates found could be partial depending on the provided dateFormat option (for example, a file name could contain info only about a day or a month). If such is the case, then it uses the next priority to determine the date used to complete it:

• Date from the baseDate option, if defined.
• Dates found in the parent folders. It searches recursively in parent folders until the input folder, completing each partial date with its parents dates. For example, a folder name could have the year info, contain folders with months info, containing files with days info, etc.
• Date from the baseDateFallback option.

TIP: Use the --dryRun option to get a preview of the results without modifying any file, allowing you to adjust the options or folder names until every date is set with a single command.

Arguments

• folder - Path to the input folder

Options

| Option | Default value | Description | Example | |---|---|---|---| | --dryRun | false | Print report only. Do not modify any file | --dryRun | | -m, --modify | false | Modify existing dates. By default, the program don't modify files already having DateTimeOriginal | --modify | | --no-modifyTime | false | Modify dates but keep original time information when present. It has no effect if modify is false | --no-modifyTime | | --no-modifyDay | false | Modify dates but keep original day when present. It has no effect if modify is false | --no-modifyDay | | --no-setDigitized | false | Do not set also DateTimeDigitized property. By default the program fills both DateTimeOriginal and DateTimeDigitized properties. This option disables that feature | --no-setDigitized | | -o, --outputFolder | - | Write modified images to this folder instead of modifying original ones. The original folder tree is recreated | --outputFolder ./modified-photos | | -c, --copyAll | false | Copy all files outputFolder, not only those being modified | --copyAll | | -u, --moveUnresolvedTo | - | After finishing, move unsupported files or files without DateTimeOriginal to a subfolder with this name. The subfolder is created under the folder in which the file was originally. | --moveUnresolvedTo no-date | | -d, --date| - | When provided, this date is set to all files. Must have ISO 8601 format, or match with any of the formats provided in the dateFormat option | --date 2022-02-12 | | -f, --dateFallback| - | If the date for a file is not found anywhere else, set this date. Must have ISO 8601 format, or match with any of the formats provided in the dateFormat option | --dateFallback 2022-02 | | -b, --baseDate| - | Date used to complete other dates when they are partial. For example, if dates in file names have only month and day, you can use this option to set the year for all dates. Must have ISO 8601 format, or match with any of the formats provided in the dateFormat option | --baseDate 2022 | | -b, --baseDateFallback| - | If the base date for a file is not found anywhere else, use this one as base date. Note that the base date for a file is calculated using its parent folder names. Must have ISO 8601 format, or match with any of the formats provided in the dateFormat option | --baseDateFallback 2022-05 | | -f, --dateFormat | ISO 8601 format | Formats used to parse dates from file or folder names or date options. Multiple values can be provided. The dates will be parsed using the first matching format. Check the date-fns docs to learn more about defining date formats | --dateFormat dd-MM-yyyy yyyy | | -r, --dateRegex | - | Regex used to extract dates from file or folder names. Regexs with a capturing group must be provided. Multiple values can be provided | --dateRegex "^year-(\S*)$" | | --no-fromDigitized | false | Do not set DateTimeOriginal property using the value from the DateTimeDigitized property. By default, if the program found the DateTimeDigitized property and DateTimeOriginal is empty, it fills it with the same value. This option disables that feature. Implicit when --date option is used | --no-fromDigitized | | --no-fromFileName | false | Do not set dates based on dates found in file names. Implicit when --date option is used | --no-fromFileName | | --no-fromFolderNames | false | Do not set dates based on dates found in folder names. Implicit when --date option is used | --no-fromFolderNames | | --no-baseDatefromFolderNames | false | Do not set base dates based on dates found in parent folder names. The program tries to complete partial dates for a file or folder using its parent folder names. This option disables that feature. Implicit when --baseDate option is used | --no-baseDatefromFolderNames | | -l, --log | info | Log level. Can be one of silly, debug, verbose, info, warn, error or silent | --log debug |

Acknowledgements

This package depends on next packages for some important internal core features:

• piexifjs - Used internally to read and write Exif data from/to image files.
• date-fns - Used internally to convert, calculate and parse dates.

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.

License

MIT, see LICENSE for details.