Kroma Player — a local music player you can rebuild

// what it does

A whole library, handled properly

Everything a collection needs — finding music, filing it, fixing its metadata and playing it back — without a subscription in sight.

Search the web, keep the file

Find tracks through YouTube Music search and pull them straight into your library, tagged and filed. What lands on disk is yours.

The library tab

Every local track in one sortable list. Show, hide, reorder and resize columns — your layout survives the next launch.

Metadata that goes deep

Title, artist, album, genre, release date — plus BPM and musical key, all editable in a dedicated track-edit tab.

Artwork, cached

Embedded cover art is extracted, cached and served by the backend, so big libraries scroll without stuttering.

Playlists & queue

Build playlists, manage a live queue with play history, and bulk-import track lists straight from an exported CSV.

Backing tracks

Import or generate an instrumental for any track and switch to it mid-playback, seamlessly, on a 150 ms crossfade.

Lyrics

A lyrics panel that fetches synced words where they exist, so the line you're hearing is the line you're reading.

Picks up where you left off

Window layout, queue state, sort order and column widths are all restored on the next launch. Close it mid-song; come back to it.

Downloading, on your terms

Audio downloading ships switched off. You turn it on, and agree to only fetch what you have the right to. Everything else works either way.

The library view listing tracks with custom columns — **Library** — every local track, your columns

Web search results with album artwork, ready to download — **Browse** — search, then keep it

Editing a track's metadata, with artwork, BPM and key fields — **Edit** — fix the tags once, properly

// architecture

Two halves, one clean seam

Kroma Player is not one program pretending to be modular. It is a backend and a frontend that genuinely do not know much about each other — and the line between them is documented, versioned and public.

Kord is the Python backend. It owns everything that isn't pixels: the SQLite library, playback, downloading, importing, artwork and the play queue. It exposes all of that as a set of named view models.

Nocturne is the official interface — a folder of QML that binds to those view models. It holds no database access, no file access and no playback logic. It is loaded from disk at startup, which is precisely why it can be replaced.

Read the GUI API

Nocturne or yours

A folder of QML loaded from disk. Decides what the app looks like and how it is navigated — and nothing else.

main.qmlviews/components/gui.json

GUI API v2

Kord python

View models, services, repositories and the vault. Everything that is not pixels lives here, behind one contract.

viewmodelsservicesrepositories SQLiteyt-dlpQt Multimedia

// interfaces

The interface is a folder

If you can write QML, you can write a Kroma Player interface. Build a folder, drop it in your vault, pick it in Settings, restart. No forking, no rebuilding, no compiler.

Write a folder

A gui.json manifest and an entry main.qml are the only required files. Everything past that is up to you.

Drop it in the vault

Copy the folder into ~/Music/venomvault/.data/gui/ — or install a package someone else published.

Pick it and restart

Settings lists every interface it finds. Choose one, relaunch, and the app comes up wearing it.

Nocturne has no special privileges. It ships as an ordinary interface package and is copied into your vault on first run — specifically so you can read it, copy it, and change it. Nothing in it is off-limits to you.

                
                .data/gui/tiny/gui.json
              
{
  "name":        "tiny",
  "title":       "Tiny Player",
  "version":     "1.0.0",
  "api_version": 2,
  "entry":       "main.qml",
  "author":      "you",
  "description": "A transport-only interface."
}

                
                .data/gui/tiny/main.qml
              
import QtQuick
import QtQuick.Controls

Window {
    width: 480; height: 560
    visible: true
    color: "#141414"

    // Album art, served by the built-in provider
    Image {
        source: "image://art/" + playerVM.artHash
        anchors.fill: parent
    }

    Button {
        text: playerVM.isPlaying ? "Pause" : "Play"
        onClicked: playerVM.togglePlay()
    }
}

That is a complete, working interface. Everything else — the queue, search, playlists, lyrics, import, export — is another view model away.

The settings panel listing installed interfaces — **Pick one** — installed interfaces, listed with author and version

The same library running under a different interface — **Or wear another** — same backend, same library, different face

// and if you like nocturne as it is

Six accents, light and dark, or whichever your desktop is on — plus an ambient mode that takes the window's colour from the album art.

Aurora Ember Bloom Verdant Ice Gold

// the vault

Your library is a folder you can pick up and move

Audio, database, artwork cache and interfaces all live inside one vault folder. Move it to another drive, another machine, a backup — point the app at it and everything is exactly where you left it.

No account. No sync service. No phoning home. The only thing that lives outside the vault is a small config file recording where the vault is.

Downloading audio ships turned off. Kroma Player has no way to know whether you hold the rights to a given track, so it doesn't assume you do. You enable it yourself, and agree to only fetch what is yours to fetch. Everything else — search, import, artwork — works either way.

~/Music/venomvault

<vault>/                    your audio, sharded
├─ mix/0001-0100/0042.opus
├─ bt/ 0001-0100/0042.opus  instrumentals
└─ .data/
   ├─ tracks.db             metadata
   ├─ covers.db             artwork cache
   ├─ session.json          window, queue, layout
   └─ gui/
      ├─ nocturne/          the official interface
      └─ your-gui/          anything else you install