A desktop music player for beets libraries. Browse and play your collection by album, artist, or recent additions.

C++ 94.2%
CMake 5.2%
C 0.4%
Shell 0.2%

Find a file

ika 9c4082119e add install script		2026-05-03 12:57:37 +02:00
src	Fix art path being relative	2026-05-03 12:55:31 +02:00
.gitignore	Initial implementation of Qt6 desktop album player	2026-03-26 10:24:02 +01:00
beetnik.desktop	Convert SVG icon to PNG at build time, add install rules and desktop entry	2026-03-26 14:32:17 +01:00
CLAUDE.md	Remove keyboard navigation and Ctrl shortcut keys	2026-04-03 13:38:32 +02:00
cmake_uninstall.cmake.in	Add uninstall target	2026-03-26 15:48:37 +01:00
CMakeLists.txt	fix for new beet path not being absolute	2026-05-03 11:23:12 +02:00
icon.svg	Convert SVG icon to PNG at build time, add install rules and desktop entry	2026-03-26 14:32:17 +01:00
install.sh	add install script	2026-05-03 12:57:37 +02:00
LICENSE	Add 3-clause BSD license	2026-03-26 14:33:06 +01:00
PLAN.md	fix hard coded path	2026-05-03 09:41:49 +02:00
README.md	I have read the code	2026-05-03 11:44:47 +02:00
resources.qrc.in	Convert SVG icon to PNG at build time, add install rules and desktop entry	2026-03-26 14:32:17 +01:00
screenshot.png	add screenshot	2026-03-26 14:52:20 +01:00

README.md

BeetNik

A desktop music player for beets libraries. Browse and play your collection by album, artist, or recent additions.

Features

Browse all albums, recently added, or a random selection
Artist list view with per-artist album browsing
Album detail view with track list
Embedded cover art via beets artpath or ID3v2 tags
Play button overlay on album hover
Persistent player bar with seek and volume controls
Click player bar artwork to open the current album

Global Media Keys (Hyprland)

BeetNik registers an MPRIS2 D-Bus interface (org.mpris.MediaPlayer2.beetnik), so media keys work system-wide via playerctl. Add to ~/.config/hypr/hyprland.conf:

bindl = , XF86AudioPlay, exec, playerctl play-pause
bindl = , XF86AudioPrev, exec, playerctl previous
bindl = , XF86AudioNext, exec, playerctl next

You can adapt to your window manager. The following put Beetnik in a scratchpad window:

bind = SUPER, b, togglespecialworkspace, special:beetnik

windowrule {
    name = beetnik
    match:class = ^beetnik$
    workspace = special:beetnik
}

Requirements

Qt 6 (Core, Gui, Widgets, Sql, Multimedia, MultimediaWidgets, DBus)
TagLib
rsvg-convert (for building the icon)

Build

cmake -B build -S . -DCMAKE_INSTALL_PREFIX=~/.local
cmake --build build -j$(nproc)

Install

cmake --install build

This installs the binary, icon, and desktop entry, then refreshes the GNOME icon and application caches.

Uninstall

cmake --build build --target uninstall

Removes all files listed in build/install_manifest.txt. Run after installing with the same --prefix.

Configuration

BeetNik reads the beets SQLite database at:

~/.local/share/beets/musiclibrary.db

Thanks

Thanks to Navidrome for the interface and the beets project.