Settings

Settings are stored in the catalog database and apply immediately; no restart is needed. Invalid values are rejected with a message explaining what to change, and nothing is saved when any value in a change is invalid.

library_root

The root folder of the Clean library, where imported photos are copied.

Type:

absolute path, or unset

Default:

unset (chosen on first import)

Validation:

must be an absolute path to an existing folder that Picturesque can create files in. Once the library has photos, the folder cannot be changed (photo locations are stored relative to it); moving a library is not supported yet. Writability is checked by creating and removing a temporary file, so read-only mounts and folders without permission are caught.

path_template

How photos are arranged inside the library. Tokens in braces are replaced with values from each photo.

Type:

text

Default:

{year|Undated}/{date}/{name}.{ext}, for example 2026/2026-10-12/IMG_0042.CR3

Validation:

must be a valid template; see Path Templates for the tokens and rules. An invalid template is rejected with a message naming the problem.

sidecar_naming

How new XMP sidecars are named (XMP sidecars). Existing sidecars are always updated where they are.

Type:

file_extension or base_name

Default:

file_extension

Values:

file_extension writes IMG_0042.CR3.xmp (darktable, digiKam); base_name writes IMG_0042.xmp (Lightroom, Bridge).

series

When photos form a series (Series).

Type:

object with max_gap_seconds and max_distance

Default:

{ "max_gap_seconds": 30, "max_distance": 16 }

Values:

max_gap_seconds: the longest pause between consecutive shots of a series, 1–3600. max_distance: the most perceptual-hash bits a photo may differ from the series’ latest photos, 0–32; lower is stricter (Visual similarity).

Changing it regroups series immediately.

ranking

How much each score counts when choosing the best photo of a series (Series).

Type:

object with sharpness, exposure, noise and aesthetic

Default:

{ "sharpness": 0.6, "exposure": 0.3, "noise": 0.1, "aesthetic": 0.4 }

Values:

numbers, zero or more, at least one of the technical weights above zero. Only the ratios matter: {1, 0, 0, 0} ranks by sharpness alone. aesthetic counts only once the CLIP model has analyzed the photos.

Changing it re-ranks series immediately.

ai

Where local AI models run (Local AI).

Type:

object with provider

Default:

{ "provider": "auto" }

Values:

auto, cpu, directml, coreml or webgpu. A provider the build lacks, or that fails to start, falls back to the CPU.

auto_pick

Which photos the app marks as keepers (Auto-pick).

Type:

object with enabled and min_quality

Default:

{ "enabled": true, "min_quality": 0.5 }

Values:

min_quality: the combined quality score a photo needs, 0–1 (shown as a percentage in Settings).

Changing it updates the suggestions immediately.

import

Watched import folders (Watched folders).

Type:

object with rescan_minutes

Default:

{ "rescan_minutes": 5 }

Values:

rescan_minutes: how often watched folders are scanned again, 0–1440 minutes. 0 scans only when a folder reports a change and when the app starts.

Where settings are stored

In the catalog database; see Data Locations.

API

get_settings

No arguments. Returns all settings:

{ "library_root": null, "path_template": "{year|Undated}/{date}/{name}.{ext}",
  "sidecar_naming": "file_extension",
  "series": { "max_gap_seconds": 30, "max_distance": 16 },
  "ranking": { "sharpness": 0.6, "exposure": 0.3, "noise": 0.1,
               "aesthetic": 0.4 },
  "ai": { "provider": "auto" },
  "import": { "rescan_minutes": 5 },
  "auto_pick": { "enabled": true, "min_quality": 0.5 } }

update_settings

Arguments: any subset of the settings. Unknown fields are rejected. Returns all settings after the change.

$ curl -s -X POST http://127.0.0.1:5174/api/commands/update_settings \
    -d '{"library_root": "/does/not/exist"}'
{"code":"invalid_arguments","message":"Cannot use `/does/not/exist` as the library folder: it does not exist. Choose an existing folder you can write to."}