Skip to content

Add theta/wl-svg-bg — live CSS-animated SVG wallpaper - #526

Draft
M4jor-Tom wants to merge 1 commit into
noctalia-dev:mainfrom
M4jor-Tom:add-wl-svg-bg
Draft

Add theta/wl-svg-bg — live CSS-animated SVG wallpaper#526
M4jor-Tom wants to merge 1 commit into
noctalia-dev:mainfrom
M4jor-Tom:add-wl-svg-bg

Conversation

@M4jor-Tom

Copy link
Copy Markdown

Plugin

  • Id: theta/wl-svg-bg
  • New plugin
  • Update to an existing plugin (version bumped in plugin.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-shell background surface, so @keyframes play live behind the
desktop.

  • Service (takeover) — claims the connected outputs with
    setWallpaperEnabled(connector, false) so Noctalia tears down its own
    Background surface where the renderer draws, then starts the renderer's user
    unit. Outputs plugged in later are claimed on onOutputsChanged. Clearing the
    Animated 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 stays
Noctalia-agnostic; the plugin is the only part that knows Noctalia exists. An
example animated SVG ships at wl-svg-bg/examples/aurora.svg, since animated
SVGs are rare enough that an empty file picker is otherwise the first-run
experience.

Complete accounting of side effects:

  • Network calls: none. The SVG is loaded from a local file:// URL.
  • Filesystem writes: one file, ~/.local/state/wl-svg-bg/env, containing
    WL_SVG_BG_SVG=<the chosen path>. The renderer reads the path from there
    rather 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 noctalia from reloading the wallpaper.
  • Spawned processes: systemctl --user start|restart|stop wl-svg-bg.service. When no wl-svg-bg.service has been declared — every
    install 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 unit
    file and never runs daemon-reload.
  • Notifications: on a missing SVG selection, a missing renderer, or a failed
    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 from
    M4jor-Tom/wl-svg-bg.py. It needs
    PyGObject with the GTK 4, WebKitGTK 6.0 and gtk4-layer-shell typelibs.
  • systemd — supplies systemctl and systemd-run, which manage the
    renderer's unit.

Both are declared in dependencies in plugin.toml. The plugin requires a
compositor implementing wlr-layer-shell; it cannot work on GNOME or KDE.

Testing

  • Tested on Niri
  • Tested on Hyprland
  • Tested on Sway
  • Tested on another compositor:
  • Noctalia version tested against:
  • Plugin API level: 17

plugin_api = 17 is the oldest level this plugin can use: below it onEnable
and the Disable/Uninstall exit reasons do not fire, which breaks both the
off-switch and teardown.

service.luau has a stub-host test suite covering the output-claim lifecycle,
the env-file diff that decides start versus restart, the transient-unit
fallback, and the failure paths that release the outputs.

Screenshots / Videos

wl-svg-bg thumbnail

Draft, deliberately. Three required statements are not true yet, and per the
template an explanation does not replace a check:

  • The thumbnail above is a direct render of the shipped examples/aurora.svg,
    not a capture made with the official generator, so that box stays unchecked.
  • No compositor box is checked and there is no capture of the plugin running.
    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

  • The directory name matches the part of id after the / in plugin.toml exactly.
  • It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
  • README.md follows the README template, documents every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
  • I created thumbnail.webp with the thumbnail generator.
  • version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
  • Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
  • I did not edit catalog.toml; CI generates it.
  • This PR touches exactly one plugin directory.

Code review attestation

  • The code is readable and not obfuscated, minified, or generated.
  • It does not download and execute remote code.
  • Every network call, filesystem write, and spawned process is something the description above accounts for.
  • I have the right to publish this code under the license declared in plugin.toml.

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant