Implement BenthicBloom GNOME 50 wallpaper extension
Adds a complete GNOME Shell 50 extension with folder-based wallpaper auto-rotation (shuffle/sequential, crossfade transitions, lock screen sync), GStreamer-backed live/video wallpapers rendered onto the shell's own Clutter stage, and OLED burn-in protection (pixel shifting, idle dimming, forced periodic rotation). Includes a top-bar quick-access indicator, a libadwaita preferences window, GSettings schema, and a Makefile for install/packaging. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RDqbdjsiisSU7CbQke4g8
This commit is contained in:
Claude
@@ -1 +1,128 @@
|
||||
# benthicbloom
|
||||
# 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.
|
||||
|
||||
## 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 file 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.
|
||||
- **OLED burn-in protection** — three independent, individually toggled
|
||||
techniques:
|
||||
- *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.
|
||||
- A top-bar indicator for quick access to rotation, live wallpaper, and
|
||||
OLED protection toggles, plus 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). If these aren't installed, the live
|
||||
wallpaper toggle stays disabled and BenthicBloom's other features work
|
||||
normally.
|
||||
|
||||
## Installation
|
||||
|
||||
### From source
|
||||
|
||||
```sh
|
||||
git clone https://github.com/quinta0/benthicbloom.git
|
||||
cd benthicbloom
|
||||
make install
|
||||
```
|
||||
|
||||
Then reload GNOME Shell — press <kbd>Alt</kbd>+<kbd>F2</kbd>, type `r`,
|
||||
press <kbd>Enter</kbd> on X11, or log out and back in on Wayland — and
|
||||
enable the extension:
|
||||
|
||||
```sh
|
||||
gnome-extensions enable benthicbloom@quinta0.github.io
|
||||
```
|
||||
|
||||
### Packaging a zip
|
||||
|
||||
```sh
|
||||
make pack
|
||||
```
|
||||
|
||||
produces `dist/benthicbloom@quinta0.github.io.shell-extension.zip`,
|
||||
installable via `gnome-extensions install <file>` or the Extensions app.
|
||||
|
||||
## Configuration
|
||||
|
||||
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
|
||||
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, mute, playback speed,
|
||||
and 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
|
||||
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.
|
||||
- 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.
|
||||
|
||||
## 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:
|
||||
|
||||
```sh
|
||||
dbus-run-session -- gnome-shell --nested --wayland
|
||||
```
|
||||
|
||||
or on a real GNOME 50 desktop, and please file an issue with any problems
|
||||
you hit.
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-or-later — see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user