kopuz

Kopuz (formerly known as Rusic)

Kopuz is a modern, lightweight, music player application built with Rust and the Dioxus framework. It provides a clean and responsive interface for managing and enjoying your local music collection.

About the Name

The kopuz is an ancient Turkic string instrument and is often considered the ancestor of many Central Asian lutes. It was traditionally used by bards and shamans.

The Kyrgyz komuz is not the same instrument, but likely a descendant of the kopuz. The Kazakh kobyz is also related, though it is bowed rather than plucked. In contrast, the Tuvan/Yakut xomus (jaw harp) is unrelated, despite the similar name.

In Turkic legend, the kopuz is linked to Dede Korkut, a legendary bard, though this is mythological rather than historical.

Discord Rust

Kopuz

Overview

Kopuz allows you to scan your local directories for audio files, or stream from your Jellyfin or Subsonic (Navidrome, etc.) server, automatically organizing everything into a browsable library. You can navigate by artists, albums, genres, or explore your custom playlists. The application is built for performance and desktop integration, utilizing the power of Rust.

Features

Installation

NixOS / Nix

Run directly without installing:

nix run github:temidaradev/kopuz

Install to your profile:

nix profile add github:temidaradev/kopuz

NixOS flake (recommended — installs as a proper system app with icon & .desktop entry):

Add kopuz to your flake.nix inputs:

inputs.kopuz.url = "github:temidaradev/kopuz";

Pass it through to your system config and add the Cachix substituter so it downloads the pre-built binary instead of compiling:

# nixos/nix/default.nix
nix.settings = {
  substituters      = [ "https://cache.nixos.org" "https://kopuz.cachix.org" ];
  trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "kopuz.cachix.org-1:J2X3AnAYhKTJW5S3aCLoA1ckonQXVNZMQvhZA0YAufw="
  ];
};

Then install the package:

# configuration.nix || machine.nix
environment.systemPackages = [
  kopuz.packages.${system}.default
];

Kopuz is soon available on Flathub. To install from source manifest:

git clone https://github.com/temidaradev/kopuz
cd kopuz
flatpak-builder --user --install --force-clean build-dir com.temidaradev.kopuz.json
flatpak run com.temidaradev.kopuz

You can also click on the file and open it with an app provider, for example KDE discover

AppImage

Note: The AppImage requires webkit2gtk-4.1 and gtk3 installed on your system — these are not bundled. On most distros with a modern desktop environment these are already present.

On Arch-based distros, if the AppImage crashes with a WebKitNetworkProcess error, either run it with:

LD_LIBRARY_PATH=/usr/lib ./rusic_*.AppImage

Or create symlinks once (requires sudo):

sudo mkdir -p /usr/libexec/webkit2gtk-4.1
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitNetworkProcess /usr/libexec/webkit2gtk-4.1/
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitWebProcess /usr/libexec/webkit2gtk-4.1/
sudo ln -s /usr/lib/webkit2gtk-4.1/WebKitGPUProcess /usr/libexec/webkit2gtk-4.1/

Build from Source

Dependencies

Arch Linux Based Systems

sudo pacman -S rust cargo dioxus-cli base-devel cmake pkgconf opus alsa-lib xdotool webkit2gtk-4.1 gtk3 libsoup3 openssl

Debian Based Systems

sudo apt install rustc cargo build-essential cmake pkg-config libopus-dev libasound2-dev libxdo-dev libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev libssl-dev
cargo install dioxus-cli

Fedora Based Systems

sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install rust cargo cmake pkgconf-pkg-config opus-devel alsa-lib-devel libxdo-devel webkit2gtk4.1-devel gtk3-devel libsoup3-devel openssl-devel
cargo install dioxus-cli

openSUSE Based Systems

sudo zypper install rust cargo cmake pkg-config libopus-devel alsa-devel xdotool webkit2gtk3-soup2-devel gtk3-devel libsoup3-devel libopenssl-devel
cargo install dioxus-cli

git clone https://github.com/temidaradev/kopuz
cd kopuz
npm install
dx serve --package kopuz

macOS

Quarantine note: If you downloaded a .dmg instead, macOS may block it. Run once to clear the quarantine flag:

xattr -d com.apple.quarantine /Applications/Kopuz.app

Where does Kopuz keep its files?

On macOS everything lives under your Library folders:

On Linux it follows the XDG spec like you’d expect:

If covers aren’t showing or the library looks off, just delete the cache folder and hit rescan.

Optimization

kopuz is built to feel snappy even with large libraries. here’s what we do under the hood:

skip what’s already indexed — the scanner keeps a HashSet of every path it’s already seen, so rescans only process new files. if you have 10k tracks and add 5 new ones, it won’t re-read the other 9995. makes a huge difference on HDDs especially.

parallel startup loading — on launch, library, config, playlists, and favorites all load in parallel with tokio::join!. before this, everything loaded sequentially and you’d stare at a blank window for a bit. now it’s near-instant.

album art caching — cover images get extracted once and saved to disk (~/.cache/kopuz/covers/ on linux, ~/Library/Caches/ on mac). we also cache the macOS now-playing artwork object in memory so it doesn’t re-decode the image every time the progress bar updates.

lazy loading images — album covers in search results, track rows, and genre views all use loading="lazy" so we’re not loading hundreds of images at once when you scroll through a big library.

non-blocking I/O — all the heavy stuff (metadata parsing, file scanning, saving library state) runs on spawn_blocking threads so the UI never freezes. the main thread stays responsive even during a full library scan.

smarter sorting — we use sort_by_cached_key instead of regular sort_by_key for library views, which avoids recalculating the sort key (like .to_lowercase()) on every comparison. small thing but it adds up with thousands of tracks.

http caching for artwork — the custom artwork:// protocol serves images with Cache-Control: public, max-age=31536000 so the webview doesn’t re-request covers it already has.

overall these changes brought the rescan time down significantly and the app feels much more responsive, especially with libraries over 5000 tracks. memory usage stays reasonable too since we’re not holding decoded images in memory longer than needed.

Tech Stack

Crypto Donation

Star History

Star History Chart

This site is open source. Improve this page.