Hidamari: a video wallpaper for Linux desktops

What problem this actually solves

Hidamari is a video wallpaper for Linux, written in Python, and it exists because the two well known ways of doing this are both shell contrivances. The README names them directly: Xwinwrap with mpv, and Komorebi. It positions itself as offering similar functionality to those, plus a list of additions.

The additions are what make it an application rather than a script. It autostarts after login. It can apply a static wallpaper with a blur effect when you do not want video playing. It detects a maximized window and fullscreen mode and pauses playback, so a video does not keep drawing behind the thing you are actually reading. There is volume control, a two-click mute and pause, an I'm feeling lucky button that picks a random video, hardware accelerated decoding, GNOME Wayland support, multi-monitor support, streaming URL support and webpage wallpaper.

The README is unusually precise about the footnotes, and those footnotes are the most useful part of the feature list. Static wallpaper with blur is currently GNOME exclusive, with other desktops possibly supported if asked for. Detecting maximized and fullscreen windows to pause playback is currently X11 only. Hardware acceleration uses VLC as the backend, and it does not work in the Nvidia plus Wayland combination. Streaming URLs use yt-dlp as the backend, tested with YouTube videos. Webpage wallpaper is described as theoretically anything from a normal page to a Unity or Godot WebGL game.

That last one is the feature with the most personality, and also the one where you are on your own when something misbehaves.

Installing from Flathub, and the package to distrust

The supported install is Flatpak, published on Flathub, and the command line path is two commands:

flatpak install flathub io.github.jeffshee.Hidamari

flatpak run io.github.jeffshee.Hidamari

The Flathub page is also the project's declared homepage, so the distribution channel and the documentation link are the same destination.

There is also an unofficial Arch Linux package in the AUR, and the README marks it clearly as maintained by the community. The table it prints lists the maintainer as None, which is a small but real signal: nobody is accountable for that build. For a desktop application that wraps VLC and yt-dlp and reaches into GNOME internals, the Flathub build is the one to start with.

For anyone who wants to build from source instead, the repository is a Meson project with a Python application under `src/`, translations in `po/`, data in `data/`, resources in `res/`, packaging manifests in `pkgs/` and a `uv.lock` for the development environment. The licence is GPL-3.0-or-later and the project requires Python 3.10 or newer.

The dependency list explains the architecture

The `pyproject.toml` is short and reads like a description of the program. Pillow handles images, so the blurred static fallback comes from there. `python-vlc` is the playback backend, which is why VLC is named in the footnotes. `yt-dlp` with the default extras is what turns a pasted URL into a stream. pydbus is the D-Bus bridge to the desktop session, requests and setproctitle round out the runtime needs.

One deliberate omission is documented in a comment: PyGObject is not listed as a dependency because it comes from the system or GNOME runtime instead. The comment also tells you how to get a working development environment, using a virtual environment with system site packages so the system PyGObject is visible.

There is a second comment worth reading if you plan to contribute. Under the uv configuration the file states that uv only manages the development environment, that the package itself is not managed by uv, and that Meson and Flatpak build the actual package. In other words, uv is a developer convenience, not the release path. That distinction is stated plainly enough that a contributor will not waste an afternoon trying to publish to PyPI.

Lint and format configuration is also inline: ruff with a line length of 100, a Python 3.10 target, and a selected rule set covering pycodestyle, pyflakes, import sorting, pyupgrade and bugbear.

A small Makefile over a Meson build

The repository ships a Makefile that is explicitly a convenience wrapper, with the real build system underneath it. The Python developer targets come first, and they are run through uv:

uv venv --system-site-packages

uv run ruff check src/

There is a `run` target that installs into a prefix and then launches the application in debug mode, which is the shortcut you will use most.

The Meson targets follow, and the default prefix is your home directory rather than a system location, so installation does not need sudo. `meson setup --prefix=... $(BUILDDIR)` configures, `meson compile` builds, `meson install` installs and a `ninja ... uninstall` target removes a previous install. The build directory is overridable, so you can keep several configured trees side by side.

Translations are handled through gettext via Meson, with a `pot` target that regenerates the template and then rewrites the placeholder header strings into the project's real title and copyright line. That is the kind of detail that shows a translation workflow is actually used rather than stubbed out, and it matters for an application with a Flathub audience.

The Flatpak manifest lives at `pkgs/flatpak/io.github.jeffshee.Hidamari.json`, referenced from the Makefile as the manifest variable, which is how the same repository produces the artifact people install.

Release history shows what breaks in practice

Three tags are published, and they are spaced far enough apart to be informative. v3.5 in June 2024 was a small rollup. v3.6 in January 2025 was a single feature, multi-monitor support for video, contributed by an outside developer who made their first contribution in that pull request. v3.7 in July 2026 is the current version and matches the version in `pyproject.toml`.

What v3.7 actually contains is worth reading closely, because it is not a feature release. It moves image files to the assets directory on the master branch, updates screenshot references, and, most interestingly, includes a fix for some CPU leaks contributed by another first-time contributor. The repository's last push was 2026-07-09, the same day the tag was published.

A CPU leak fix in a video playback app is not a minor patch. A wallpaper player runs for hours behind everything else you do, so an idle CPU cost is the difference between a wallpaper and a background process you notice. That contribution is the most useful thing in the release notes.

The gap between January 2025 and July 2026 is the other thing to weigh. This is a small project maintained primarily by one person, with sponsorship links, a Discord, and an explicit request in the README for contributions and issues. At 2124 stars and 132 open issues it has real adoption and a correspondingly long issue queue, and the release cadence suggests bursts of work rather than steady throughput.

GNOME has a sibling project worth knowing about

The README points GNOME users at another project by the same author, Hanabi, described as a new project that is still in its infancy but has the potential to become more integrated with GNOME Shell.

That recommendation is context for everything else in this repository. Hidamari is a standalone GTK application that manages its own window and talks to the session, which is why it needs footnotes about X11 versus Wayland and about GNOME exclusivity for the blurred static wallpaper. A GNOME Shell extension would sit inside the compositor instead, which is a different design with a different set of constraints and no window to place. The author recommending it for GNOME users rather than trying to fold it into Hidamari suggests Hidamari's own ceiling on that desktop.

For anyone deciding between them: Hidamari is installable today from Flathub and works across desktops to whatever extent the footnotes allow, while Hanabi is the option that would integrate more deeply with GNOME if that matters to you. The README also carries the Japanese gloss for the project name, meaning a sunny spot or exposure to the sun, which is a nicer touch than most project descriptions manage.

The repository includes a documentation directory and a data directory, and the application icons come from Freepik via Flaticon, credited in the README.

Editorial conclusion

Hidamari solves a small problem properly and is candid about the parts it does not cover. The pause on fullscreen and the blurred static fallback are the two features that decide whether a video wallpaper is pleasant or irritating, and both are here. The limits are equally clear in the README's own footnotes: the static wallpaper with blur is GNOME exclusive, pausing on a maximized window is X11 only, and hardware decoding through VLC does not work in the Nvidia plus Wayland combination, which is a real hole on a common setup. Install from Flathub rather than the AUR package, because the unofficial package lists no maintainer. If you are on GNOME with Wayland and an Nvidia card, check that combination before you invest time in configuring playlists.

Frequently asked questions

Official sources

1. jeffshee/hidamari on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases