From f8adc2594f038549929cd1323f2e47bf5b6a518e Mon Sep 17 00:00:00 2001
From: Quinta0 <0pietroquintavalle0@gmail.com>
Date: Fri, 7 Aug 2026 13:52:54 +0200
Subject: [PATCH] edited the readme

---
 README.md | 132 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 70 insertions(+), 62 deletions(-)

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 <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:
+Reload GNOME Shell (<kbd>Alt</kbd>+<kbd>F2</kbd>, type `r`, <kbd>Enter</kbd>
+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 <file>` 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).