thumbsup logo thumbsup

--albums-from <string>

As detailed in the intro section, albums are a virtual concept in thumbsup. Files can belong to arbitrary albums regardless of where they are on disk. This setting determines how the photos and videos are grouped into albums.

The simplest value is a raw string where / denotes a hierarchy of albums. For example, --albums-from "Holidays/Tokyo" specifies that all files should go in an album called Tokyo, inside an album called Holidays. A more typical use case is to use keywords to generate albums on the fly based on the photos being processed.


The value %path automatically expands to the nested folder structure, relative to the input folder. For example:

File path Pattern Value
Holidays/Tokyo/IMG_0001.jpg %path Holidays/Tokyo
Holidays/Tokyo/IMG_0001.jpg Family/%path Family/Holidays/Tokyo

The value {format} automatically expands to the date the photo/video was taken. The format must be a valid moment.js format.

File date Pattern Value
2017-10-21 {YYYY} 2017
2017-10-21 {YYYY/MM} 2017/10
2017-10-21 {YYYY}/{MM - MMM} 2017/10 - October
2017-10-21 Years/{YYYY}/{MM} Years/2017/10

This always uses the creation date if available in the EXIF data. If there is no EXIF data, it tries to infer the date from the filename, or defaults to the file’s mtime. You can change mtime with many tools such as Unix’s touch command.


The value %keywords expands to every ITPC keyword present in the photo. Keywords containing / are interpreted as nested hierarchies of keywords. For example:

Keywords Pattern Albums
beach, sunset %keywords beach, sunset
beach, sunset Tags/%keywords Tags/beach, Tags/sunset
beach, beach/sunset, beach/sunrise Tags/%keywords Tags/beach, Tags/beach/sunset, Tags/beach/sunrise
Multiple albums

A file can belong to zero, one or many albums. On the command line, simply specify the flag multiple times:

thumbsup --albums-from "Folders/%path" --albums-from "Years/{YYYY}"

If using a config file, specify the patterns as an array:

  "albums-from": ["Folders/%path", "Years/{YYYY}"]
Custom function

For more complex album structures, you can also specify a fully custom mapper using file:// followed by a file path (relative to the current directory).

--albums-from "file://mapper.js"

For example you can separate photos and videos:

module.exports = file => {
  return ? ['Videos'] : ['Photos']

Or you can put all 5-star photos into a “Best photos” album:

module.exports = file => {
  return (file.meta.rating === 5) ? ['Best photos'] : []

Or have special logic based on your directory structure:

// if your folders are called "2016 [this event]"
const eventRegex = /(\d\d\d\d) \[([a-z\s]+)\]/
module.exports = file => {
  const match = eventRegex.exec(file.path)
  if (match) {
    const year = match[1]
    const event = match[2]
    return [`Events/${year}/${event}`]
  } else {
    return ['Events/Unsorted']

You can either group all logic into a single function, or specify many mappers such as:

--albums-from "Photos/{YYYY}" --albums-from "file://5star.js" --albums-from "file://events.js"

--sort-albums-by <choice>

Criteria Detail
title Sort alphabetically by album title
start-date Sort by the date of the earliest picture in the album
end-date Sort by the date of the latest picture in the album

Defaults to start-date.

--sort-albums-direction <choice>

Album sorting direction, either asc or desc. Defaults to asc.

--sort-media-by <choice>

How to sort photos and videos inside each album.

Criteria Detail
filename Sort all media alphabetically by filename
date Sort all media by date. The date is taken from EXIF data if possible, and otherwise infered from the filename or the file’s mtime.

Defaults to date.

--sort-media-direction <choice>

Media sorting direction, either asc or desc. Defaults to asc.