Haruna: a Qt/QML front end for libmpv, and how to install it

What Haruna adds on top of mpv

Haruna is a media player built with Qt/QML and libmpv. That sentence from the README is the whole architectural claim: the playback core is mpv's library, and Haruna is the window, the controls and the configuration around it. The project is hosted on KDE's GitLab instance at invent.kde.org under multimedia/haruna, and the README points to haruna.kde.org for screenshots.

The README lists the behaviours it says set it apart from other players: video preview on the seek and progress bar, playing online videos through youtube-dl, a playlist that toggles on mouse-over and overlays the video, auto-skip of chapters containing certain words, configurable shortcuts and mouse buttons, middle-click on the progress bar to jump to the next chapter, and custom mpv commands that can run at startup or on a keyboard shortcut.

Read that list carefully and a pattern appears. Almost every item is a UI affordance or a configuration hook, not a playback capability. Chapter skipping by keyword, a playlist that appears when the pointer crosses it, a middle-click shortcut: these are decisions about how a video window should behave. The value proposition is therefore narrow and honest. If you are happy with mpv's defaults and use it from a terminal, Haruna gives you little. If you want mpv's rendering inside a desktop application that respects KDE conventions, that is the gap it fills.

The Qt/QML and libmpv split, and what it means for configuration

The repository layout reflects the split. The top level holds CMakeLists.txt, a cmake directory, config-haruna.h.cmake, and a src directory, alongside packaging files: .flatpak-manifest.yml, snapcraft.yaml, .gitlab-ci.yml and .kde-ci.yml. There is also a po directory for translations, a data directory, LICENSES and REUSE.toml, and a file named org.freedesktop.ScreenSaver.xml.

That last file is a small but telling detail. Inhibiting the screen saver during playback is handled through the freedesktop D-Bus interface rather than through mpv itself. It is the kind of thing a Qt application does and a command-line player does not. The presence of config-haruna.h.cmake means build-time configuration is generated into a header, so the compiled binary carries settings that come from the CMake configure step. Dependencies, according to the README, are printed by cmake when building rather than documented as a list.

The custom mpv commands feature is the clearest expression of the design. Rather than reimplementing mpv's option surface in a settings dialog, Haruna lets you attach mpv commands to startup and to keyboard shortcuts. The QML layer stays thin and the mpv layer stays authoritative. The cost is that some behaviour lives in two places: what you can do from the interface, and what you can only do by writing an mpv command into a configuration field.

Installing Haruna with Flatpak

The README's install section gives one route and it is Flatpak. The badge links to Flathub, and the two commands below install the application and then start it. The application ID is org.kde.haruna, which is what you pass to both commands.

flatpak install flathub org.kde.haruna
flatpak run org.kde.haruna

After the first command completes you should see the application listed among your installed Flatpaks; the second launches the player window. If flatpak is not present on your system, the README links to the Flatpak setup guide at flatpak.org/setup rather than describing the steps itself. That is the extent of the documented install instructions.

For a first real use, the README's feature list suggests where to look. Open a local video file, then move the pointer over the progress bar: the video preview on seek is one of the behaviours the project claims as a differentiator. Hovering over the playlist area toggles the overlay. Middle-clicking the progress bar jumps to the next chapter. Those three interactions exercise the parts of Haruna that are not simply mpv.

Building Haruna from source

The README gives a four-command build using CMake and Ninja. The clone comes from KDE's GitLab, and the build directory is named build.

git clone https://invent.kde.org/multimedia/haruna.git
cd haruna
cmake -B build -G Ninja
cmake --build build
cmake --install build

The README states that dependencies will be printed by cmake when building. That is the only dependency documentation provided, which means the configure step is not just a build step but the way you discover what you are missing. Expect the first cmake -B build run to be the informative one; on a machine without the Qt and mpv development packages it will report what it cannot find. The README does not list package names for any distribution, so there is nothing to copy from it beyond the commands above.

Note the generator flag: -G Ninja means Ninja must be installed and on your PATH, because CMake will not fall back silently to another generator when one is named explicitly. The install step writes into the system prefix by default, so a local prefix is worth considering if you do not want to touch system directories. The README does not discuss prefixes, uninstallation or rollback.

Where Haruna is the wrong tool

The most concrete limitation is the one the README states about itself: dependencies are printed by cmake when building. There is no dependency list, no per-distribution package names, and no supported-versions matrix. Anyone building from source is expected to iterate against the configure output. For a distribution packager that is fine, because the packaging files in the repository (.flatpak-manifest.yml, snapcraft.yaml) already encode the dependency set for those targets. For an individual on an unusual system it means the build is a discovery process.

The README does not document rollback, nor how to remove a source install. The cmake --install build command installs; there is no documented uninstall counterpart, and no mention of a package manifest that would let you reverse it.

There is a second boundary, less about bugs and more about fit. Haruna is a desktop application, and the repository contains KDE CI configuration and translation infrastructure. If you want a player that runs headless, that is scriptable as a library, or that you can embed into another application, this is the wrong shape: the interesting parts here are the QML interface and the desktop integration, not a reusable playback API. And if your playback needs are already met by mpv's command line, the feature list in the README is a list of things you would be adding rather than replacing.

Haruna against mpv and against a general-purpose player

The honest alternative is mpv itself. Both use the same playback core, since Haruna is built on libmpv. The difference is entirely in approach: mpv exposes an option surface and an input configuration file, and you get behaviour by writing configuration. Haruna exposes a window with menus, a progress bar with preview, and a playlist that overlays the video, and you get behaviour by clicking. Haruna's custom mpv commands feature is the bridge between the two positions: it lets you keep mpv-style configuration for the things the interface does not cover, without giving up the interface.

Against a general-purpose desktop player that ships its own playback stack, the difference is the opposite one. Haruna inherits mpv's rendering and format handling rather than maintaining a separate decoding path, so the playback behaviour you get is mpv's. What you trade for that is dependency on libmpv and on Qt being present and compatible, which is exactly why the README's install section leads with Flatpak: bundling sidesteps the compatibility question.

There is also a packaging dimension. The repository carries both a Flatpak manifest and a snapcraft.yaml, and the README presents Flatpak as the route for users. If your environment is one where Flatpak is unavailable or unwanted, the alternative is the source build, with the dependency-discovery caveat described above.

Licence and maintenance signals in the repository

The README carries SPDX headers: the file itself is CC-BY-4.0, attributed to George Florea Bănuș. The repository has a LICENSES directory and a REUSE.toml, which is the REUSE compliance mechanism that records per-file licensing. That tells you the project takes licence metadata seriously at the file level, but the README does not state the licence of the source code, and the LICENSES directory contents are not reproduced here. If the licence of the application code matters to your use, read LICENSES and REUSE.toml in the repository rather than assuming.

On maintenance, the repository is not archived. No last-push date is available, so there is no basis for describing how frequently it is updated. The presence of .gitlab-ci.yml, .kde-ci.yml and a po directory indicates it runs KDE's CI and participates in KDE's translation workflow, which is a structural fact about the project's home rather than a statement about release cadence.

Upgrade cost depends on the install route. A Flatpak install is updated through Flatpak. A source install has no documented upgrade path beyond repeating the build and install commands, and no documented rollback if the new build misbehaves. That asymmetry is worth weighing before choosing the source route.

Editorial conclusion

Haruna is for people who already like mpv's playback behaviour but want a KDE-style window around it: the README's feature list is about preview on seek, playlist overlay, chapter skipping and custom mpv commands, not about a different decoder. It is not the right choice if you need a player you can install and configure without a desktop toolchain, since the README's own install route is Flatpak and the build route prints its dependencies from cmake rather than listing them. Before adopting it, run the cmake configure step on your machine and read the dependency output, because that is the only place the project states what it needs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository