Skip to content

Allow overriding terminal screensaver frame rate - #8556

Open
howdeploy wants to merge 2 commits into
omacom:quattrofrom
howdeploy:fix/screensaver-frame-rate
Open

howdeploy wants to merge 2 commits into
omacom:quattrofrom
howdeploy:fix/screensaver-frame-rate

Conversation

@howdeploy

Copy link
Copy Markdown

Fixes #8554

Summary

  • let the terminal screensaver read OMARCHY_SCREENSAVER_FRAME_RATE
  • keep the existing 120 FPS behavior when the variable is unset
  • reject values outside the supported 1–240 range before launching ttfx
  • document the UWSM environment override and cover custom/default/invalid values with a headless shell test

Context

The QXL guest documented in #8554 freezes its Wayland session after the stock 120 FPS Foot/ttfx screensaver starts. The kernel recorded 117 TTM eviction failures, a QXL VRAM allocation failure, and repeated qxl_fence_wait stalls. Disabling the screensaver prevents the failure, but currently there is no supported middle ground between editing the package-owned script and disabling the feature entirely.

This intentionally does not auto-detect QXL or change the default for everyone. It provides a small, reversible mitigation and a controlled way to test a conservative rate such as 20 on constrained displays.

PR #7193 would make the terminal implementation a fallback behind a native Wayland client. That client should preserve the same override if it becomes the default; this draft is limited to the implementation currently shipped by quattro.

Testing

  • test/shell.d/screensaver-test.sh
  • bash -n bin/omarchy-screensaver test/shell.d/screensaver-test.sh
  • git diff --check
  • ./test/all: test/cli passed and the new screensaver test passed. The shell suite reported seven unrelated environment/fixture failures that also reproduce at the untouched base commit: missing omarchy-pkgs checkout coverage, two existing command-path/animation tests, a QR fixture mismatch, and restricted writes under the host $HOME.

I did not deliberately run the live 120 FPS failure again: recovering this guest requires stopping the graphical session, and #8554 already contains the complete user-journal and kernel timeline. The override path itself is exercised through a pseudo-terminal with stubbed ttfx, hyprctl, and process cleanup.

@howdeploy

Copy link
Copy Markdown
Author

Runtime validation

Validated SHA 5a2838dbe2051e91a2f04d59d8045989571d83a1 on the QXL VM from #8554.

  • test/shell.d/screensaver-test.sh: PASS.
  • bash -n bin/omarchy-screensaver test/shell.d/screensaver-test.sh: PASS.
  • Invalid values 0, 241, twenty, 01, and -1 were rejected with exit 1 and the documented 1–240 validation error.
  • Real ttfx cmdline with the variable unset: --frame-rate 120 (5-second probe only; the known dangerous 120 FPS load was not reproduced).
  • Real ttfx cmdline with OMARCHY_SCREENSAVER_FRAME_RATE=20: --frame-rate 20.
  • Real ttfx cmdline with OMARCHY_SCREENSAVER_FRAME_RATE=30: --frame-rate 30.
FPS Duration New TTM/QXL allocation/fence failures Result
120 historical: first failure at 48s, 117 TTM failures in that boot non-zero baseline from #8554
20 1,200s 0 PASS
30 1,200s 0 PASS

The 20/30 FPS runs used the same screensaver input and deterministic decrypt effect (seed 8556). Each run stopped cleanly: no ttfx or test launcher remained, the original Quickshell PID stayed alive, Hyprland IPC remained responsive, and QXL Virtual-1 stayed connected with DPMS on. The pre-existing stay-awake/screensaver-off state and QXL DPMS guard were left unchanged.

This validates the override as a mitigation on this specific QXL VM, not as a kernel/QXL fix.

@howdeploy
howdeploy marked this pull request as ready for review August 28, 2026 06:18
Copilot AI balanced review requested due to automatic review settings August 28, 2026 06:18

Copilot AI left a comment

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.

Pull request overview

Adds a configurable terminal screensaver frame rate while preserving the 120 FPS default and validating supported values.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

  • Reads and validates OMARCHY_SCREENSAVER_FRAME_RATE.
  • Documents the UWSM override.
  • Adds shell coverage for default, custom, and invalid values.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

File Description
bin/omarchy-screensaver Validates and forwards the configured frame rate.
manual/13-toggles-idle-screensaver.md Documents frame-rate configuration.
test/shell.d/screensaver-test.sh Tests frame-rate behavior.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread manual/13-toggles-idle-screensaver.md Resolved
Comment thread test/shell.d/screensaver-test.sh Resolved
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.

120 FPS ttfx screensaver triggers QXL TTM failures and freezes the session

3 participants