PhotoStructure's advanced settings

June 30, 2020

PhotoStructure’s settings page is simple and only offers a handful of configuration options.

There are many configurable settings within PhotoStructure, though, including:

how “nice” PhotoStructure is with your system’s CPU: should it auto-pause imports if CPU exceeds 75% (which is the default), or is it running on a server, and can use 100% of the CPU?
is it OK to send error reports? (this defaults to true, but you can opt-out of sending error reports via this setting)
what filters are enabled to allow or reject files from being imported into your library?
what sizes of preview images should be generated during import?
should we transcode videos on import?

🧑‍🤝‍🧑 Twice the fun with TWO settings files 🔗

Note that PhotoStructure has two settings files:

“system settings,” and
“library settings.”

Breaking out the settings into two files is somewhat inconvenient, and certainly unconventional, but it allows for PhotoStructure libraries to be portable across computers.

System settings 🔗

System settings are specific to a computer. Examples include what paths to scan, where to save logfiles, and what percent of the CPU can be used during imports.

The system settings will be found in your PhotoStructure application settings directory.

Linux: ~/.config/PhotoStructure/settings.toml
macOS: ~/Library/Application Support/PhotoStructure/settings.toml
Windows: %APPDATA%\PhotoStructure\settings.toml
Docker: your bind-mount for /ps/config/settings.toml

Library settings 🔗

Library settings are specific to your library. Most settings are library settings. Examples include what preview image sizes to create, what pattern to use for automatic organization, and what taggers should be enabled during imports.

The library settings will be found in (your library directory)/.photostructure/settings.toml. Note that the .photostructure directory in your library will be hidden. If you don’t see this directory:

On macOS, hold down ⌘ and shift then touch . (the period key).
On Windows, click File > “Change folder and search options”. Select the View tab. In Advanced Settings > Hidden files and folders, select “Show hidden files, folders, and drives”. Click OK.
On Ubuntu, click the hamburger menu in the titlebar and select “Show Hidden Files”.

Editing TOML 🔗

The settings files are formatted as TOML, but you only need to know a couple things:

Lines that start with a # are comments, and ignored
Every OS has a text editor that can edit these files. TextEdit on macOS and Notepad on Windows work just fine, but make sure you overwrite settings.toml: if you write to settings.toml.txt, that will be ignored.
Most settings have reasonable defaults, which are provided after the description. Remove the # from the beginning of the line with the default to override.
The order of settings doesn’t matter.

So, for example, to change the logWebRequests system setting to true, change this:

# Write an access log for all web requests?
#
# logWebRequests = false

to this (note the “# " has been deleted, and “false” was changed to “true”):

# Write an access log for all web requests?
#
logWebRequests = true

I haven’t installed PhotoStructure yet. What are all the settings I can play with? 🔗

A complete list is here.

If you are testing an alpha or beta build, switch to the alpha or beta branch to make sure you’re looking at the correct defaults.

Know that there are a lot of settings! We’ve attempted to pick defaults that will work for most people: basically if there’s been a heuristic or judgement call, it’s been shoved into settings rather than hard-coding the value. There won’t be a surprise test on any of this, next Tuesday, honest.

If you find any values whose default values don’t work for you, please tell us via chat, email, or reddit: we want PhotoStructure to “just work” for most people!

If PhotoStructure writes settings only after I start, how do I configure things beforehand? 🔗

Many settings impact what photos and videos are imported into your library, and how they are imported (like disabling video transcoding, for example).

Solution 1: Use `PS_START_PAUSED` 🔗

You can “pause” PhotoStructure’s initial import by setting the PS_START_PAUSED environment variable to true (see instructions here for how to set environment variables on your platform).

Set the environment variable
Install and launch PhotoStructure
Fill out the initial welcome page
Click start, and then quit PhotoStructure
Edit the system or library settings to taste. Remember to save your changes.
Un-set PS_START_PAUSED (or set it to false)
Restart PhotoStructure

Solution 2: Use environment variable overrides 🔗

All settings can be overridden with environment variables: just set them before starting PhotoStructure, and your overridden values will be used instead of PhotoStructure’s defaults.

Solution 3: Use “rebuild” 🔗

If you already installed and started playing with PhotoStructure, but found that there’s several settings you want to change, don’t panic, just:

Shut down PhotoStructure
Edit the system or library settings to taste. Remember to save your changes.
Restart PhotoStructure
From the navigation menu, select “Rebuild”.

This can take a while, depending on the size of your library.

⏲ Duration settings 🔗

This section only applies to PhotoStructure version 2.1 and later!

Prior versions of PhotoStructure required duration settings to be set in milliseconds, but it’s hard (at least for me) to see 3600000 and see an hour–my eyes go wobbly after the fourth zero.

Version 2.1 supports friendlier values for these duration settings, like statTimeoutMs, which all end with “Ms” (short for Milliseconds).

Duration settings may now use any of the following formats:

1. Numeric values 🔗

These will always be interpreted to be in milliseconds:

60000 is 1 minute
1200000 is 20 minutes
3600000 is 1 hour
86400000 is 1 day

2. ISO 8601 duration strings 🔗

The ISO 8601 duration standard is a bit ungainly, but at least it’s a standard:

PT1M is 1 minute
PT20M is 20 minutes
PT1H is 1 hour
P1D is 1 day
p4dt5h6m7.890s is 4 days, 5 hours, 6 minutes, 7 seconds, and 890 milliseconds.

3. Friendly duration strings 🔗

This duration format is ([value] [unit])*, where “value” is numeric, and “unit” is one of

years, year, or y
weeks, week, or w
days, day, or d
hours, hour, or h
minutes, minute, or m
seconds, second, or s
milliseconds, millisecond, ms, or just omit the unit.

Note:

Casing doesn’t matter–Years, YEARS, years, Y, and y are all equivalent.
Use whatever unit variant you’d like–the long and short versions (hours vs hour vs h) are all equivalent.
Note that there isn’t a “month” unit: m means minutes.
Fractional values are supported, but only by using “.” as a decimal separator (like 2.5 days).
Whitespace and commas around values and units are ignored.

So, for the above examples:

1m or 1 minute is 1 minute
20m or 20 minutes is 20 minutes
1h or 1 hour is 1 hour
1d or 1 day is 1 day
4d5h6m7s890, 4d 5h 6m 7s 890ms, or 4 days, 5 hours, 6 minutes, 7.890 seconds is 4 days, 5 hours, 6 minutes, 7 seconds, and 890 milliseconds.

How PhotoStructure parses durations 🔗

PhotoStructure will first attempt to parse duration settings values as numeric, then as ISO 8601, then as a friendly duration string.

PhotoStructure stores durations using friendly duration strings.

A couple things to note 🔗

PhotoStructure should be shut down before you edit settings.
The settings files will only exist on your system after you’ve installed PhotoStructure and clicked “Start” on the welcome page.
If you’d like to see a comprehensive list of settings, see here.

Automatic upgrades 🔗

New versions of PhotoStructure frequently add new system or library settings.

PhotoStructure upgrades your settings.toml files automatically.
Prior settings files are archived in a backup directory.
Custom values are retained, but any comments you may have added will not be preserved.