Hanabi Is A Live Wallpaper For GNOME Desktop

Hanabi gnome shell live wallpaper

Hanabi is a GNOME Shell extension that allows using a live wallpaper (video) on the GNOME desktop, with support for both X11 and Wayland.

According to the developer, the extension “is not even close to alpha quality”, but it's already usable, albeit you'll need to install it manually since it's not available on the GNOME Shell extensions website.

This live wallpaper GNOME extension currently supports playing a local video as your desktop background, with or without audio, and the ability to set the audio volume. From the extension top bar menu, you can pause the video and mute/unmute the audio.

To get the video playback to use less CPU, the extension comes with experimental support for VA-API hardware acceleration, as well as the ability to use the new Nvidia statless decoders. For best performance, the extension can utilize clappersink from Clapper (a GNOME media player that uses GStreamer as a media backend and renders everything via OpenGL)—this needs to be installed as a native package, and not as a Flatpak package. The extension GitHub page has a performance comparison on using Hanabi live wallpaper for GNOME with and without clappersink.

From the extension preferences, you can control how the live wallpaper fits within the monitor, allowing users to set the fit mode to fill, contain, cover and scale-down.

This is a short video I've recorded with Hanabi GNOME live wallpaper running on GNOME 44 (X11):

Here's another video recorded by the extension developer.

Hanabi video wallpaper works with GNOME Shell 42 and 43. [[Edit]] It now also supports GNOME 44 with both Wayland and X11, with a caveat: the top bar is hidden when logging in. There is a workaround for this though: if you switch workspaces, the top bar is visible again, and remains so, fixing this issue. In my test, the extension did not work with GNOME Shell 44 running on Wayland on both Ubuntu 23.04 and Fedora 38.

You might also like: Video Livestream Wallpaper For Your GNOME, Xfce Or bspwm Desktop

It's also worth noting that looking at the bug reports, it appears Hanabi GNOME Shell video wallpaper should work with multiple monitors, but I couldn't test this as I'm currently only using one monitor. Also, the extension works with the Desktop Icons extension, so your desktop icons will continue to be displayed on top of the video wallpaper.

For the future, there are plans to pause the wallpaper when there are fullscreen or maximized windows, and stop the live wallpaper when the laptop runs on battery and resume when it's on AC. There's also a pull request to render websites as the live wallpaper, instead of a local video.

Install Hanabi GNOME live wallpaper

Arch Linux / Manjaro: you can install the extension from AUR.

For how to install Hanabi GNOME live wallpaper on Debian / Ubuntu / Pop!_OS or Fedora, see the instructions below.

1. Start by installing the dependencies:

Debian / Ubuntu / Pop!_OS: 

sudo apt install git meson ninja-build npm libgtk-4-media-gstreamer

For Ubuntu 22.10 and 23.04, and Debian 12 and Unstable it's recommended to also install Clapper from the repositories:

sudo apt install clapper

Unfortunately, Clapper is not in the official repositories for Ubuntu 22.04 / Pop!_OS 22.04 and older Debian releases. In that case, you'll need to build Clapper from source. Or you can use the Clapper DEB package I've built for Ubuntu 22.04 / Pop!_OS 22.04, which you can grab from here. Without Clapper, the live video wallpaper will cause very high CPU usage. Installing Clapper from Flathub will not work with this video wallpaper.


sudo dnf install git meson ninja-build npm clapper

2. Next, grab the Hanabi GNOME live wallpaper code from GitHub and install it using:

git clone https://github.com/jeffshee/gnome-ext-hanabi.git

cd gnome-ext-hanabi

./run.sh install

3. Enable the extension.

The extension should now be installed. To be able to enable it, logout / log back in or, if you're using X11, press Alt + F2 and type r to restart GNOME Shell. Enable the extension using the GNOME Extensions app or GNOME Extension Manager. The extension menu should now show up on the top bar.

For best video performance (less CPU usage), it's best to open the Hanabi extension preferences and enable the Experimental VA Plugin if you're using an Intel / AMD GPU, and the Nvidia Stateless Decoders for Nvidia GPUs. Also enable the Forcegtk4paintablesink option. It's important to note that in my test, GNOME Shell needs to be restarted for these changes to be applied so on X11 you can restart it by pressing Alt + F2 and typing r, while on Wayland you'll need to logout and relogin.

In case the video wallpaper doesn't start, make sure you're able to play that video on your GNOME desktop using a GStreamer-based video player, e.g. Totem (Videos) or Clapper. If that doesn't work, you may be missing some GStreamer plugins (search and install them from your Linux distribution's official repositories).

You might like: Embed An Audio Visualizer On Your Linux Desktop Background Using GLava