Configuration

Undertone keeps its settings in a plain text file, ~/.config/undertone/config.toml (under $XDG_CONFIG_HOME when that is set), so you can keep them in your dotfiles and have every Mac look the same.

  • Edits apply on their own. Undertone notices a change to the file within a second, whether you edit it, a dotfiles manager (chezmoi, stow, yadm) writes it, or a git pull brings it in. No restart.
  • Settings write it. A change in Settings or the menu writes the whole file again, in the layout below. Comments of your own are lost when that happens; keep notes elsewhere, or make your changes in the file.
  • A link stays a link. If config.toml is a symbolic link (stow, or chezmoi in symlink mode), Undertone writes to the file it points at.
  • Only settings. What is showing now, when it last shuffled, and Pause stay in Undertone's own preferences, so a shuffle or a pause never changes the file.
  • No file, no problem. Without one Undertone uses the defaults, and writes the file the first time you change a setting. Open Config File in the menu writes it and opens it.
  • Mistakes stay small. A key or value Undertone cannot use falls back to that setting's default and the rest of the file still applies; the menu shows the first problem, and undertone config --check lists them all, by line.

Every setting, at its default (undertone config --defaults prints this):

# Undertone's settings. Undertone reads this file when it changes, and writes it (in this layout, without
# comments of your own) when you change a setting from its settings window or menu.
# https://mpdreamz.github.io/undertone/reference/configuration/

[style]
mode = "shuffle"
always = "mesh"  # the style when mode = "always"
never = []

[tonality]
mode = "shuffle"
always = "ember"  # the tonality when mode = "always"
never = []
hemisphere = "auto"

# Effects go over every picture, in a fixed order: glass, halftone, vignette, bloom, posterize, paper, leak,
# dither, grain. Each has its own section; on = false turns it off and keeps its settings here.
[effects]
random = false
random_never = []

[effects.vignette]
on = true
strength = 1.0

[effects.grain]
on = true
amount = 0.035

[effects.dither]
on = false
levels = 4
cell = 1.0

[effects.halftone]
on = false
spacing = 8.0
angle = 45.0

[effects.glass]
on = false
width = 36.0
strength = 0.55

[effects.bloom]
on = false
threshold = 0.45
strength = 0.6

[effects.leak]
on = false
strength = 1.0
warmth = 1.0

[effects.paper]
on = false
strength = 1.0

[effects.posterize]
on = false
bands = 7

[shuffle]
every = "never"
on_wake = false

[screen]
spaces = "same"
hide_notch = false
round_corners = false

[title]
show = false
title = "{computer}"
subtitle = "{user} ยท macOS {os}"

[motion]
lock_screen = false
speed = "normal"
movement = "normal"
settle = 2.5
easing = "ease-out"
  1. shuffle (a new style each shuffle) or always
  2. left out of shuffles: mesh, flow, waves, orbs, rings, dunes, contour, silk, aurora, bauhaus, blobs
  3. shuffle, season (suits the time of year, never mono) or always
  4. left out of shuffles: ember, tide, aurora, dusk, moss, glacier, citrus, mono
  5. whose seasons: auto (from the Mac's region), north or south
  6. one more effect on each shuffle, chosen at random
  7. left out: dither, halftone, glass, bloom, leak, paper, posterize
  8. 0 to 3; 1 is the usual
  9. 0 to 0.2; 0.035 subtle, 0.06 strong
  10. levels per colour, 2 to 16
  11. points per cell, 1 to 4
  12. points between dots, 4 to 24
  13. degrees, 0 to 90
  14. points per flute, 12 to 96
  15. how much each flute magnifies, 0 to 0.9
  16. how bright a part must be to glow, 0 to 1
  17. 0 to 1.5
  18. 0 to 2
  19. 0 rose to 1 amber
  20. 0 to 2
  21. bands of lightness, 3 to 16
  22. never, hourly, 3h or daily
  23. a new picture on login and wake
  24. same (one picture on every space) or different
  25. a black menu bar strip on displays with a notch
  26. black corners, curved like macOS's windows
  27. {computer}, {user}, {os} and {host} are filled in
  28. needs Undertone chosen as the screen saver
  29. calm, normal or lively
  30. subtle, normal or strong
  31. seconds the slow-down on unlock takes, 1 to 5
  32. glide, ease-out or spring

The file is a small part of TOML: sections, key = value, text in double quotes, numbers, true and false, and # comments. A file needs only the keys you want to change.
undertone config Where the file is.
undertone config --defaults A file with every setting at its default, to start from.
undertone config --check [file] What Undertone cannot use in the file (or in file), by line; exits with 1 when there is anything, for a dotfiles repository's checks.

Older settings move over on their own: from Undertone 0.3's preferences into the file, and a file in Undertone 0.4's layout (with a [picture] section) is read and written again in this one. A locked style or tonality becomes mode = "always", random becomes shuffling among all, grain becomes [effects.grain], and a chosen effect is turned on.