Live Wallpaper for GNOME

Hanabi 花火【はなび】(n) fireworks

( ・ω・)o─━・*:'・:・゜'・:※

GNOME Shell Extension - Hanabi

If you like my project, please consider buying me a coffee!! (⁎˃ ꇴ ˂⁎)ｯ

Also please don't forget to hit that star button! 🌟
Feel free to open an issue for problems or suggestions 🤗
Your support is truly appreciated!

Join our Discord!

Demo 📽️

Please click on the image to view (redirect to YouTube)

Wallpaper used in demo

Hanabi is migrating to TypeScript!

[!IMPORTANT] Moving to TypeScript for better type safety and maintainability~ ✨

Active development now happens on the typescript branch — GNOME 50+, Wayland only — merging into the main branch on July 15, 2026.

Until then, the main branch stays on JavaScript so existing community packages and their CI builds keep working through the transition. The javascript branch enters maintenance mode — bugs still get fixed, but no new fireworks there. (・ω・)ノ

GNOME Shell Support

Version	42–44	45–50	50+
Status	⚠️	✅	✅
Branch	legacy	javascript	typescript

[!TIP] On GNOME 50? You're encouraged to give the TypeScript version a try!

Installation

1. Clone the branch for your GNOME Shell version

• GNOME 50 and later (TypeScript, Wayland only) 🔥

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

• GNOME 45–50 (JavaScript, X11 and Wayland)

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

1. Run the installation script

   cd gnome-ext-hanabi
   make install
   

   Build dependencies

   • typescript branch: meson, node, and npm
   • javascript branch: meson

2. Restart GNOME Shell

3. Enable the Hanabi extension

4. Choose your video wallpaper in the extension preference window

Distro-specific Guides

See the distro-specific guides for installation instructions.

Troubleshooting

1. The video doesn't play / The extension is enabled but nothing happens
   The GTK4 media backend is not pre-installed on some distributions (such as PopOS).

   To install the backend:
   sudo apt install libgtk-4-media-gstreamer

2. High CPU usage during video playback (proprietary NVIDIA)
   Your hardware acceleration may not work properly, see this issue.

   To delete the GStreamer cache:
   rm -rf ~/.cache/gstreamer-1.0/
   After that, check if gst-inspect-1.0 nvcodec reports all its features.

3. Blur My Shell — wallpaper becomes semi-transparent
   If you use the Blur My Shell extension with Applications → Applications blur → Enable all by default turned on, add an exception for the Hanabi renderer.

   In Blur My Shell settings, go to Applications → Applications blur → Blacklist and add:
   io.github.jeffshee.HanabiRenderer

Advanced Usage

Video backend selection & scripting

Hanabi uses gtk4paintablesink (from GStreamer) as the default video sink, which offers good performance and broad compatibility.

Optionally, clappersink from Clapper can be used instead via Preferences → Developer → Prefer clappersink. Clapper must be installed from the package manager and not from Flatpak/Snap for this to work.

There is a known compatibility issue with clappersink on native installs with GStreamer 1.26+. If you encounter crashes after enabling this option, please disable it.

For more advanced customization, learn how to write scripts for Hanabi extension!
Check out the scripting guide for detailed instructions and examples.

Get Involved 🚀

Contributors are welcome! Let's make Hanabi extension better together~

Development

See the development guide for instructions.

Translation

If you're interested in translating, you can help on Hosted Weblate.

Contributors ✨

Made with contributors-img.
Icons made by Freepik from Flaticon