Skip to content

Let a theme override the screensaver's art and ttfx settings - #14622

Open
NiWe03 wants to merge 7 commits into
omacom:quattrofrom
NiWe03:feat/theme-screensaver
Open

NiWe03 wants to merge 7 commits into
omacom:quattrofrom
NiWe03:feat/theme-screensaver

Conversation

@NiWe03

@NiWe03 NiWe03 commented Oct 8, 2026 •

Copy link
Copy Markdown

Idea from discussion #14303.

Problem

omarchy-screensaver always reads ~/.config/omarchy/branding/screensaver.txt and runs ttfx --random-effect with each effect's default settings. Switching themes changes nothing about it — with a custom theme and matching wallpapers, the screensaver is the one part of the desktop that can't follow along.

What this does

  • A theme may ship screensaver.txt at its root. If present, it takes precedence over the global branding file. If absent, behavior is exactly as today.
  • A theme may also ship screensaver.conf: extra ttfx arguments, one per line (blank lines and # comments ignored) — e.g. restricting --random-effect to specific effects via --include-effects/--exclude-effects, a different --frame-rate, or a fixed canvas size. Any flag set there replaces the script's built-in default for that same flag, since ttfx (clap) errors out if a flag is passed twice.
  • Both are opt-in and plain data (no code), so omarchy-theme-set already stages them for first-party themes and themes installed from a git repo — no change needed there.

Effect modes

screensaver.conf also accepts two directives that the script reads itself: mode=random|single|first and effect=<name>. Lines after effect= are arguments for that effect (e.g. its colors), so a theme can pin one effect, or start with it and go random afterwards (idea from #11178). Without them nothing changes; an unknown mode or effect falls back to random.

What's not included, and why

Colors are not derived automatically from colors.toml: color flags like --final-gradient-stops are effect-specific and ttfx rejects them together with --random-effect. A theme sets them itself after effect= instead.

Testing

  • Added test/shell.d/screensaver-theme-test.sh (effect modes, fallback to branding file, theme file precedence, screensaver.conf args overriding defaults — all mocked, no real ttfx/Hyprland).
  • ./test/cli and ./test/shell pass (pre-existing unrelated failures on this machine: missing omarchy-pkgs checkout, missing omasnap, a couple of compositor-dependent tests — none touch screensaver code).
  • Manually verified live: generated ASCII art from a theme's unlock.png via omarchy-transcode-ascii, dropped it in as that theme's screensaver.txt, ran omarchy theme set <theme> then omarchy-launch-screensaver force — the screensaver showed the theme's art instead of the global branding logo.

omarchy-screensaver always read the global branding screensaver.txt,
so switching themes never changed it. A theme's screensaver.txt now
takes precedence when present, falling back to the branding file
otherwise. A theme can also ship screensaver.conf with extra ttfx
arguments (effect selection, frame rate, canvas size); any flag it
sets there replaces the script's built-in default for that flag
instead of duplicating it, since ttfx errors on a repeated flag.

Both files are plain data, so staging already keeps them for both
first-party and installed themes without any change to
omarchy-theme-set.
@greptile-apps

greptile-apps Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The changes affect theme customization for the screensaver.

Fix the dropped final configuration line before merging.

Findings

  1. P1 Last setting gets skipped ▶

Summary

Themes can supply screensaver art and settings. The latest changes add:

  • Themes can show their own screensaver art.
  • Themes can tune screensaver effects and choose when a named effect runs.

The new parser skips the last setting when screensaver.conf has no trailing newline.

Reviews (5) · Last reviewed commit: "Document screensaver effect modes" · Reviewed by Greptile

Comment thread bin/omarchy-screensaver Resolved
Comment thread test/shell.d/screensaver-theme-test.sh Resolved
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
@jandrusk

Copy link
Copy Markdown

Nice theming hook — theme screensaver.txt / screensaver.conf with the default-flag conflict avoidance looks right, and the test coverage helps.

One small note: theme args are appended after -i, so a theme conf can also pass another -i and override the art path. That's probably fine under the usual "themes are trusted" model, but worth a one-liner in docs/theming.md so theme authors know conf can replace the input file too.

Related (different knob): #11732 lets shell.json pin a single ttfx effect.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@NiWe03

NiWe03 commented Oct 12, 2026

Copy link
Copy Markdown
Author

Thanks for the note! Good catch on the docs gap. I checked: a second -i doesn't override, ttfx fails with the argument '--input-file <INPUT_FILE>' cannot be used multiple times. So I added a line to docs/theming.md saying the art goes in screensaver.txt, not -i in the conf.

@NiWe03

NiWe03 commented Oct 19, 2026

Copy link
Copy Markdown
Author

Added theme-selectable effect modes, picking up the idea from #11178 (and the suggestion there to make the effect selectable instead of changing the default). screensaver.conf now accepts mode=random|single|first and effect=<name>. Everything after effect= is passed to that effect, so a theme can pin e.g. the Matrix rain with its own colors. Without these lines nothing changes. Example and docs are in docs/theming.md.

Comment thread bin/omarchy-screensaver
theme_args=() effect_args=() screensaver_mode=random screensaver_effect=
[[ -f $conf ]] || return 0

while IFS= read -r line; do

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Last setting gets skipped

The new while read loop skips the last line of screensaver.conf when it has no trailing newline. For example, --frame-rate followed by a final 30 now passes only --frame-rate to ttfx, which rejects the missing value and cannot show the art. The previous parser kept that line.

Keep a nonempty final value even when read returns failure at EOF: while IFS= read -r line || [[ -n $line ]]; do.

Suggested change
while IFS= read -r line; do
while IFS= read -r line || [[ -n $line ]]; do

@greptile-apps

greptile-apps Bot commented Oct 19, 2026

Copy link
Copy Markdown
Contributor

Want your agent to iterate on Greptile's feedback? Try greploops.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants