diff --git a/README.md b/README.md index 7150192..40b660c 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,49 @@ # BenthicBloom -A GNOME Shell 50 extension that automatically rotates your wallpaper, -supports looping video (live) wallpapers, and includes built-in -protection against OLED burn-in. +A GNOME Shell 50 extension that rotates your wallpaper, supports looping +video (live) wallpapers, and protects OLED displays from burn-in. ## Features -- **Auto rotation** — pick one or more folders and BenthicBloom cycles - through the images inside them on a timer, in sequential or shuffled - order, with an optional crossfade between changes. The chosen wallpaper - can also be applied to the lock screen. -- **Live wallpapers** — play a looping video *or animated GIF* as your +- **Auto rotation**: pick one or more folders and BenthicBloom cycles + through the images inside them on a timer, sequential or shuffled, with + an optional crossfade. Can also apply to the lock screen. +- **Live wallpapers**: play a looping video or animated GIF as your desktop background. Frames are decoded with GStreamer and rendered - directly by GNOME Shell's own Clutter stage (no external, incompatible - Clutter build involved). Playback can automatically pause on battery - power or while a window is fullscreen. Automatic rotation is - automatically suspended while a live wallpaper is actually on screen - (and resumes afterward), since changing the static wallpaper would - otherwise repaint over the video. -- **OLED burn-in protection** — three independent, individually toggled - techniques: + directly on GNOME Shell's own Clutter stage. Playback can pause on + battery power or while a window is fullscreen. Auto rotation suspends + while a live wallpaper is on screen and resumes after. +- **OLED burn-in protection**, three independent toggles: - *Pixel shifting*: nudges the background a few pixels on a slow drift cycle so the same subpixels aren't lit continuously. - - *Idle dimming*: fades the background to a configurable lower - brightness after the system has been idle for a while, and restores - it the moment you're back. - - *Forced rotation*: guarantees the wallpaper changes after a maximum - static duration, even if automatic rotation is otherwise switched - off. + - *Idle dimming*: fades the background after the system has been idle + for a while, restores it when you're back. + - *Forced rotation*: guarantees a wallpaper change after a maximum + static duration, even if auto rotation is off. - A top-bar indicator for quick access to rotation, live wallpaper, and - OLED protection toggles, plus a "Next Wallpaper" action, and a full + OLED protection toggles, a "Next Wallpaper" action, and a full libadwaita preferences window. ## Requirements - GNOME Shell 50. -- For live wallpapers: GStreamer with its `good` and `base` plugin sets - (e.g. `gstreamer1.0-plugins-good` and `gstreamer1.0-plugins-base`, or - your distribution's equivalent) — the `good` set is also what provides - animated GIF decoding. If these aren't installed, the live wallpaper - toggle stays disabled and BenthicBloom's other features work normally. +- For live wallpapers: GStreamer's `base` and `good` plugin sets (the + `good` set also provides GIF decoding), with GObject-Introspection data. + Without them the live wallpaper toggle stays disabled; everything else + works normally. + +```sh +# Arch +sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav + +# Debian/Ubuntu +sudo apt install gstreamer1.0-plugins-base gstreamer1.0-plugins-good gir1.2-gst-plugins-base-1.0 + +# Fedora +sudo dnf install gstreamer1-plugins-base gstreamer1-plugins-good gobject-introspection +``` + +Restart GNOME Shell after installing (log out and back in on Wayland). ## Installation @@ -51,9 +55,8 @@ cd benthicbloom make install ``` -Then reload GNOME Shell — press Alt+F2, type `r`, -press Enter on X11, or log out and back in on Wayland — and -enable the extension: +Reload GNOME Shell (Alt+F2, type `r`, Enter +on X11; log out and back in on Wayland), then enable the extension: ```sh gnome-extensions enable benthicbloom@quinta0.github.io @@ -70,55 +73,60 @@ installable via `gnome-extensions install ` or the Extensions app. ## Configuration -Open preferences from the panel indicator's "Wallpaper Settings…" entry, +Open preferences from the panel indicator's "Wallpaper Settings..." entry, or run: ```sh gnome-extensions prefs benthicbloom@quinta0.github.io ``` -- **General** — panel indicator visibility, lock screen syncing, debug +- **General**: panel indicator visibility, lock screen syncing, debug logging, and the folders scanned for wallpapers. -- **Rotation** — enable/disable, interval, shuffle vs. sequential order, - and crossfade transition settings. -- **Live Wallpaper** — enable/disable, video file, source folders to pick - a video/GIF from, mute, playback speed, and power-saving pause behavior. -- **OLED Protection** — master switch plus independent controls for - pixel shifting, idle dimming, and forced periodic rotation. +- **Rotation**: enable/disable, interval, shuffle vs. sequential order, + crossfade settings. +- **Live Wallpaper**: enable/disable, video file, source folders, mute, + playback speed, power-saving pause behavior. +- **OLED Protection**: master switch plus independent controls for pixel + shifting, idle dimming, and forced periodic rotation. ## Architecture ``` -extension.js Entry point: wires up the three managers + indicator -prefs.js libadwaita preferences window -lib/settingsKeys.js GSettings key name constants -lib/logger.js Small logging wrapper gated by the debug-logging setting -lib/wallpaperSource.js Async folder scanning for image files -lib/shuffleBag.js No-immediate-repeat random ordering for shuffle mode -lib/rotationManager.js Timer-driven wallpaper rotation + crossfade overlay -lib/liveWallpaper.js GStreamer video playback rendered onto a Clutter actor -lib/oledProtection.js Pixel shifting, idle dimming, forced rotation -lib/indicator.js Top-bar quick-access menu -icons/ Bundled symbolic icons for the preferences window -schemas/ GSettings schema +extension.js Entry point: wires up the three managers + indicator +prefs.js libadwaita preferences window +lib/settingsKeys.js GSettings key name constants +lib/logger.js Small logging wrapper gated by the debug-logging setting +lib/wallpaperSource.js Async folder scanning for image files +lib/shuffleBag.js No-immediate-repeat random ordering for shuffle mode +lib/rotationManager.js Timer-driven wallpaper rotation + crossfade overlay +lib/gstreamerAvailability.js Non-blocking GStreamer init/registry check + availability probe +lib/liveWallpaper.js GStreamer video playback rendered onto a Clutter actor +lib/oledProtection.js Pixel shifting, idle dimming, forced rotation +lib/indicator.js Top-bar quick-access menu +icons/ Bundled symbolic icons for the preferences window +schemas/ GSettings schema ``` ## Known limitations -- The live wallpaper currently renders across the full stage as a single - layer, so on multi-monitor setups the video spans across all monitors - as one canvas rather than being tiled per-monitor. +- The live wallpaper renders across the full stage as a single layer, so + on multi-monitor setups the video spans all monitors as one canvas + instead of being tiled per-monitor. - Pixel shifting and idle dimming rely on GNOME Shell's private - `Main.layoutManager._backgroundGroup` and `Meta.IdleMonitor` APIs, which - are not part of the stable extension API and could change in future - shell versions. + `Main.layoutManager._backgroundGroup` and `Meta.IdleMonitor` APIs, not + part of the stable extension API, and could change in future shell + versions. +- GStreamer's registry scan is skipped (trusting the existing cache) + unless no cache exists yet, to avoid blocking gnome-shell's main thread, + and therefore the whole screen, for several seconds right after login. + A background subprocess refreshes the cache afterward so newly + installed plugins still become visible eventually. ## Testing -This was developed and validated (JSON, GSettings schema compilation, -and JavaScript syntax) without a live GNOME Shell 50 session available in -the development environment. Before relying on it, test in a nested -session: +This was developed and validated (JSON, GSettings schema compilation, and +JavaScript syntax) without a live GNOME Shell 50 session available in the +development environment. Before relying on it, test in a nested session: ```sh dbus-run-session -- gnome-shell --nested --wayland @@ -129,4 +137,4 @@ you hit. ## License -GPL-3.0-or-later — see [LICENSE](LICENSE). +GPL-3.0-or-later, see [LICENSE](LICENSE).