Repository navigation
Wallpaper System
In ii-p3drovfx the wallpaper isn't a static picture behind everything — it's the heart of the desktop. It generates your color scheme, moves with your workspaces, carries your Desktop Widgets, zooms away when the Overview opens, can be a looping video or a full Steam Wallpaper Engine scene, and even turns into a music-video stage when you're listening to something good.
- Ctrl + Super + T — open the Wallpaper Selector and pick one. The Material palette regenerates from the image automatically.
- Ctrl + Super + Alt + T — feeling lucky: a random one from your collection.
- Pick a video file in the selector and it plays as your background (needs
mpvpaper). - Want a Steam Wallpaper Engine scene? See Wallpaper Engine below.
- Super + Z — toggle Media Mode, the full-screen now-playing experience.
The Wallpaper Selector is a proper browser, not just a file dialog: register multiple wallpaper directories, sort by name or modification date, and — the nice touch — filter your collection by color with the color-filter toolbar. Prefer the system file picker? There's a toggle for that. The launcher's /wallpaper action gets you there fast, and /konachanwallpaper grabs one from the internet feeling lucky.
The left-sidebar Wallpaper Browser module searches Wallhaven or Unsplash directly from the shell — with sorting options, an anime-results toggle (Wallhaven), and configurable download folders (including a separate NSFW directory, kept out of your main collection).
- Separate lock-screen wallpaper — the lock screen gets its own image and its own Material color handling; swap desktop/lock wallpapers from Settings anytime.
- Separate light-mode wallpaper — your normal wallpaper becomes the dark one, a second image serves light mode, and automatic dark mode swaps both palette and background on schedule.
And every change can run through the Matugen color pipeline, re-theming the entire shell from the new image — see Customization for the full theming story.
The wallpaper (and the widget canvas riding on it) shifts with what you do:
- Workspace parallax — the image pans as you switch workspaces, with a configurable zoom factor and optional looping
- Sidebar parallax — opening a sidebar nudges the background
- Vertical mode (with an auto option), invertible axes, adjustable intensity, and a separate factor for how strongly widgets follow
- Blur when windows open — the wallpaper blurs (configurable radius) as soon as a workspace has windows, keeping empty desktops crisp and busy ones calm
- Gradient blur — a directional gradient blur band (e.g. top-to-bottom) for that frosted-edge look
- Workspace blur, zoom-out animations — when the Overview or Cheat Sheet opens, the desktop can pull away beneath the UI (eight styles; details on the Overview page)
Large wallpapers are downscaled smartly (scaleLargeWallpapers), and the whole background can hide while a fullscreen app runs.
Wallpaper changes animate — pick a style: Crossfade (default), Random, Circle Pit, Circle Select, Magic, Peel, Transition, Pixelate or Stripes. Or disable the animation entirely if you're a person of sudden change.
Point the selector at a video file and the shell plays it as your background through mpvpaper. The Wallpapers service detects video sources automatically and enforces the few constraints that come with them — effects that need static-image processing (like the Gnome-style overview zoom) are locked while a video is active, with the compatible defaults kept available. Thumbnails are generated so video wallpapers preview nicely in the selector.
Yes, that Wallpaper Engine. With linux-wallpaperengine installed, the shell can run Steam Workshop scenes as your background: set the workshop ID and assets path, then tune FPS limit, volume (or silent mode), audio processing, mouse interaction, parallax, scaling mode, screen span, fullscreen-pause behavior — and an option to pause the scene whenever windows are open, so it only burns GPU when you're actually looking at it.
Media Mode has grown its own page — Media Mode — covering the immersive layout, the built-in local music player and its queue, crossfade, and where every option lives. The summary below still applies.
Playing music? Media Mode transforms the desktop into a full-screen now-playing experience (toggleable per monitor): blurred album art (opacity, blur radius and Material background shape configurable), an animated background (with speed control — and a gentle warning that motion isn't for everyone), synced lyrics with horizontal or vertical highlight styles and a millisecond offset adjustment, a player switcher, seek bar, volume slider, and audio visualizers (Waves, Bars or Radial). It can even re-color the whole shell from the album art.
The show-off feature, switched on from inside Media Mode (it never starts on its own, and stops when Media Mode closes): instead of blurred album art, the shell can find the current song's actual music video (search suffix configurable, default "official music video"), fetch it with yt-dlp (up to a chosen resolution) and play it behind the Media Mode UI via mpvpaper — with background dimming for readability and a live color sampler that keeps the shell's accent in sync with the video every few hundred milliseconds.
A quietly brilliant feature for laptop users: Work Safety can automatically guard your desktop in public. When the Wi-Fi network name matches configured keywords (university, cafe, eduroam, guest…), the shell can swap away an inappropriate wallpaper — and a matching clipboard guard watches for NSFW-keyword content. Both triggers and keyword lists (network names, filenames, links) are fully configurable under Config.options.workSafety. Present in class with confidence.
Settings → Background is the hub: wallpaper & selector options, parallax, blur, transitions, zoom animations, Wallpaper Engine, Media Mode and Music Video. Persistent state lives under Config.options.background (with wallpapers, wallpaperSelector and workSafety alongside).
| Piece | Role |
|---|---|
modules/ii/background/ |
Background.qml / BackgroundRoot.qml (the per-screen background window), wallpaper/ (image rendering & size probing), parallax/, blur/, compositor/, shaders/, MediaMode*.qml (see [[Media Mode |
modules/ii/wallpaperSelector/ |
The selector UI: directories, sorting, color filtering, image options |
services/Wallpapers.qml |
Wallpaper state, video detection, constraint enforcement |
services/WallpaperBrowser.qml |
Wallhaven / Unsplash search |
services/MusicVideoService.qml + services/VideoColorSampler.qml
|
Music-video fetching and live color sampling |
scripts/colors/switchwall.sh (and switchwall_vynx.sh) |
The wallpaper-switch pipeline: mpvpaper / wallpaperengine lifecycle, Matugen invocation, accent handling, thumbnails |