Key Concepts
This page explains the fundamental entities and ideas that underpin how Kombiner stores and processes your music library. Understanding the data model will help you interpret the UI, write plugins, and troubleshoot unexpected behavior.
Track
A track is the central entity in Kombiner. Every track represents a unique piece of music — not a file, but a logical record that may or may not have a file attached.
A track record contains:
| Field | Description |
|---|---|
title | Track title |
artist | Primary artist name(s) |
album | Album or release title |
bpm | Beats per minute |
key | Musical key (e.g. A min, F# maj) |
genre | Genre tag(s) |
label | Record label |
year | Release year |
file_path | Absolute path to the local audio file, if acquired |
service_links | Map of service name → track URL (e.g. spotify, tidal, beatport) |
enrichments | Map of plugin ID → enrichment result (see below) |
Tracks are deduplicated: if the same recording appears in multiple import sources, Kombiner merges them into one row using title + artist normalization. The service_links field preserves references to all matched sources.
Enrichment
An enrichment is the result of running an enrich plugin against a single track. Enrichments are stored per-plugin — they do not overwrite the track’s base fields unless you explicitly promote a value.
Each enrichment record has:
- Plugin ID — which plugin produced this result
- Status — one of
done,error,pending,not_found, orskipped - Data — the payload returned by the plugin (BPM, key, genre, label, popularity, etc.)
- Timestamp — when the enrichment was last run
Because enrichments are independent, you can run multiple enrich plugins on the same track without conflict. If Beatport and local disagree on BPM, both values are stored and visible. This is especially useful when you want to cross-reference metadata quality across sources.
The track table displays enrichment coverage as N / M badges — N tracks successfully enriched out of M total — for each active plugin. Adding a new plugin sets N to 0 immediately, making coverage gaps obvious at a glance.
Plugin
A plugin is a unit of automation in Kombiner. Plugins are small programs that implement one or more pipeline stages — import, enrich, or acquire.
Technically, each plugin consists of:
plugin.toml— A manifest that declares the plugin’s name, version, author, stage, and required permissions.- A Rhai script — The executable logic, written in Rhai, a lightweight scripting language designed for embedding in Rust applications.
Plugin Permissions
Because plugins can interact with the network, filesystem, and browser, Kombiner uses a permission model to limit what a plugin can do. A plugin must declare which permissions it needs in plugin.toml:
| Permission | What It Allows |
|---|---|
browser | Open a headless Chrome instance (used for login flows and scraping) |
Pipeline Run
A pipeline run is a record of a single execution of a plugin. Every time an import, enrich, or acquire plugin runs — whether triggered automatically in the background or manually by the user — Kombiner logs a pipeline run.
Each run record includes:
- Which plugin executed
- Start time and end time
- Number of tracks processed, created, updated, and errored
- Any error messages or warnings produced during execution
Pipeline runs form an audit log that lets you trace exactly what happened to your library over time. You can browse the current session run history from the Logs panel in Settings to understand why a specific track was added, why an enrichment failed, or how long an import took.
Import Cursor
The import cursor is a per-plugin resume marker that records the position reached at the end of the last successful import run. Think of it as a bookmark.
When an import plugin runs, it processes tracks page by page (or event by event). After each batch, it saves the cursor to the database. If the run is interrupted — by closing the app, a network timeout, or an API rate limit — the next run reads the saved cursor and continues from that point rather than restarting from scratch.
This makes large initial imports (tens of thousands of tracks) safe to interrupt and resume, and makes subsequent incremental syncs fast because the plugin only fetches records newer than the cursor.
Deduplication
When multiple import sources contain the same track, Kombiner merges them into a single library row using title + artist normalization.
The merged track retains service_links entries for every source it was found in, preserving full traceability.
Playlists and Favorites
Kombiner organizes tracks beyond the flat library view with:
- Playlists — Named, ordered lists of tracks. Playlists are arranged in a tree structure that supports nested folders, so you can organize playlists into groups (e.g. a “Gigs” folder containing one playlist per set). You can reorder tracks and playlists using drag-and-drop.
- Favorites — A special built-in view that surfaces any track you’ve starred. Favorites behave like a playlist but are system-managed.
The Bin
The Bin is Kombiner’s soft-delete mechanism. When you delete a track from your library, it moves to the Bin rather than being permanently removed, so it won’t be added again to the library if it comes from different sources. You can browse the Bin, restore tracks back to the main library. This protects against accidental deletions during bulk operations.