Add theta/wl-svg-bg — live CSS-animated SVG wallpaper - #526
Draft
M4jor-Tom wants to merge 1 commit into
Draft
Conversation
A [[service]] plugin that yields Noctalia's Background surface on the outputs it owns and drives wl-svg-bg, an external WebKitGTK layer-shell renderer that plays an SVG's CSS animation live instead of rasterizing one frozen frame. Falls back to a transient systemd unit where no wl-svg-bg.service is declared, so it works without the renderer's home-manager module. Writes one file, ~/.local/state/wl-svg-bg/env; makes no network calls. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TnBu6LjZ6EUJ5dgdL6XBUD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plugin
theta/wl-svg-bgplugin.toml)What it does
Renders a CSS-animated SVG as the wallpaper with the animation actually
running. Ordinary wallpaper tools rasterize an SVG to one frozen frame; the
renderer this plugin drives hands the file to a WebKit view on a
wlr-layer-shellbackground surface, so@keyframesplay live behind thedesktop.
takeover) — claims the connected outputs withsetWallpaperEnabled(connector, false)so Noctalia tears down its ownBackground surface where the renderer draws, then starts the renderer's user
unit. Outputs plugged in later are claimed on
onOutputsChanged. Clearing theAnimated SVG setting is the off-switch: it releases every output and stops
the renderer.
The renderer itself (
wl-svg-bg) is a separate program and staysNoctalia-agnostic; the plugin is the only part that knows Noctalia exists. An
example animated SVG ships at
wl-svg-bg/examples/aurora.svg, since animatedSVGs are rare enough that an empty file picker is otherwise the first-run
experience.
Complete accounting of side effects:
file://URL.~/.local/state/wl-svg-bg/env, containingWL_SVG_BG_SVG=<the chosen path>. The renderer reads the path from thererather than from a command line, so paths containing spaces survive. The
plugin compares the file's current contents before writing and only restarts
the renderer when the path actually changed, which is what keeps a plain
systemctl --user restart noctaliafrom reloading the wallpaper.systemctl --user start|restart|stop wl-svg-bg.service. When nowl-svg-bg.servicehas been declared — everyinstall that does not use the project's home-manager module — it falls back to
systemd-run --user --collect --unit=wl-svg-bg.service -p Restart=on-failure -p EnvironmentFile=<the file above> wl-svg-bg. The plugin never writes a unitfile and never runs
daemon-reload.start.
If the renderer cannot start at all, the plugin hands every output back to
Noctalia and notifies, so a broken setup falls back to the normal wallpaper
rather than to a bare compositor background.
External dependencies
wl-svg-bg— the renderer, a separate program fromM4jor-Tom/wl-svg-bg.py. It needs
PyGObject with the GTK 4, WebKitGTK 6.0 and gtk4-layer-shell typelibs.
systemd— suppliessystemctlandsystemd-run, which manage therenderer's unit.
Both are declared in
dependenciesinplugin.toml. The plugin requires acompositor implementing
wlr-layer-shell; it cannot work on GNOME or KDE.Testing
plugin_api = 17is the oldest level this plugin can use: below itonEnableand the
Disable/Uninstallexit reasons do not fire, which breaks both theoff-switch and teardown.
service.luauhas a stub-host test suite covering the output-claim lifecycle,the env-file diff that decides
startversusrestart, the transient-unitfallback, and the failure paths that release the outputs.
Screenshots / Videos
Draft, deliberately. Three required statements are not true yet, and per the
template an explanation does not replace a check:
examples/aurora.svg,not a capture made with the official generator, so that box stays unchecked.
A still frame cannot show the one thing this plugin exists for, so a short
screen recording of the animation on the background layer is what should land
here before review.
Marking ready for review once those are done.
Checklist
idafter the/inplugin.tomlexactly.plugin.toml,README.md,thumbnail.webp, andtranslations/en.json.README.mdfollows the README template, documents every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.thumbnail.webpwith the thumbnail generator.versionfollows semver and is bumped in this PR;plugin_apiis the oldest API level this plugin requires.catalog.toml; CI generates it.Code review attestation
licensedeclared inplugin.toml.