Haruna: A Qt/QML Video Player That Puts mpv Features in a Modern Shell

What Haruna Solves and Who It Is For

Haruna addresses a specific gap: users who like mpv's playback engine but find its configuration file approach unwieldy. The README lists features that set it apart from other players, such as a video preview on the seek bar, a playlist that overlays the video on mouse-over, and the ability to auto-skip chapters containing certain words. This is aimed at desktop Linux users, especially those in the KDE ecosystem, who want a graphical interface to control mpv's advanced behaviors without writing lua scripts or editing mpv.conf. It is not a player for everyone; it assumes you already know what mpv is and why you might want its features, and it targets a niche within that group: people who prefer a mouse-driven, visually rich interface over keyboard-centric minimalism.

How Haruna Works: Qt/QML as a Control Surface for libmpv

The architecture is straightforward from the description: Haruna is built with Qt/QML for the user interface and libmpv for playback. The QML layer renders the controls, the progress bar, the playlist overlay, and the settings panels. libmpv does the heavy lifting of decoding, rendering, and seeking. The README mentions 'custom mpv commands' that can be run at startup or on a keyboard shortcut, which means Haruna exposes a way to pass arbitrary commands directly to the mpv core. This is a key mechanism: instead of reimplementing player logic, Haruna becomes a frontend that translates GUI actions into mpv commands. The seek preview is one example; it likely uses mpv's ability to generate thumbnails or to display a frame at a specific time, though the README does not specify the exact implementation. The chapter skipping feature also relies on mpv's chapter metadata, and the 'auto skip' logic scans chapter titles for user-defined words. This design keeps the player lightweight in terms of code, but it also means that any limitation in libmpv becomes a limitation in Haruna.

Installation and Build: Two Paths, One Flatpak Default

The README gives two installation routes. The recommended one for end users is Flatpak. The exact commands are: 'flatpak install flathub org.kde.haruna' and then 'flatpak run org.kde.haruna'. This is a single command after Flatpak is set up, and it bundles the runtime, so users do not need to worry about system dependencies. The build path is for developers or those who want a native install. The steps are: clone the repository from 'https://invent.kde.org/multimedia/haruna.git', then run 'cmake -B build -G Ninja', then 'cmake --build build', and finally 'cmake --install build'. The README notes that dependencies will be printed by cmake, which is a pragmatic approach but also a warning: you will not know what to install until you try. This is a minor friction point. The build uses Ninja as the generator, which is common in KDE projects. There is no mention of packaging for other systems, so Flatpak is the primary distribution channel.

Feature Highlights: What Sets It Apart

The README lists six features that distinguish Haruna. The video preview on the seek or progress bar is a visual convenience that many players lack. The playlist overlay, toggled by mouse-over, is a clever use of screen real estate; the playlist appears only when you need it. The auto-skip chapter feature is unusual; it allows you to skip openings or endings by specifying words like 'intro' or 'credits' in chapter titles. Configurable shortcuts and mouse buttons are standard but welcome. The quick jump to the next chapter by middle-clicking the progress bar is a specific interaction that some users will find efficient. Finally, custom mpv commands can be bound to keyboard shortcuts or run at startup, which gives advanced users a way to extend Haruna without editing config files directly. These features are not groundbreaking individually, but together they target a user who wants mpv's power with a more discoverable interface.

Limitations and When It Is the Wrong Tool

Haruna's main limitation is its reliance on mpv and the KDE/Qt ecosystem. If you are not a KDE user, the Qt dependencies might feel heavy. More importantly, the README does not mention any support for plugins or extensions beyond custom mpv commands. Consult the current documentation and mpv integration before relying on a particular extension mechanism. The youtube-dl integration is a single feature, and it depends on an external tool that may break if youtube-dl itself is unmaintained or blocked by video sites. Playback of online videos depends on the external downloader and the target service. KDE's release notes list Haruna 1.9.0 on 2026-10-30, so the absence of releases on a particular repository mirror is not evidence that development has stopped. For a simple player that just plays local files, a lighter option like mpv itself or VLC would be more appropriate.

Alternatives and How They Differ

The most direct alternative is mpv itself, which Haruna wraps. mpv is a command-line player with a minimal GUI, and it is configured through a config file and lua scripts. Haruna offers a graphical interface and mouse interactions, but it does not replace mpv's flexibility. If you are comfortable with text configuration, mpv gives you total control without the Qt overhead. Another alternative is VLC, which is a full-featured player with its own GUI, supports plugins, and has a broader codec and streaming support. VLC does not use mpv, so it has a different architecture and a larger codebase. The difference in approach is clear: Haruna is a thin layer over mpv, while VLC is a standalone player with its own engine. For KDE users, there is also Dragon Player, which is simpler but less feature-rich. Haruna's niche is the mpv power user who wants a GUI, and the alternative is either learning mpv's config or moving to a heavier player like VLC.

Maintenance and Upgrade Considerations

KDE's application page lists release history, including Haruna 1.9.0 on 2026-10-30, and identifies the application licence as GPL-3.0-or-later. It also links to the source repository and provides Flatpak and distribution-package installation options. For source builds, check the current repository's dependency requirements and the relevant licence files; individual documentation and assets may have different licences.

Editorial conclusion

Adopt Haruna if you are a KDE or Qt user who wants a graphical player that exposes mpv features like custom commands and chapter skipping, and you are comfortable with Flatpak or building from source. Avoid it if you need a mature, long-stable player with a large plugin ecosystem, or if you prefer a minimal player without playlist overlays and online video hooks. Before adopting, verify that the build dependencies are satisfied on your system, check the bug reporting guide for known issues, and confirm that the youtube-dl integration works with your preferred online video sources.

Frequently asked questions

Official sources

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