Rediscover music on your machine

Find the next track without giving up your library

Turn a large local collection into a searchable library. Start from a track or a written idea, then shape useful candidates into crates and set previews.

Start the quickstartOpen the project guideRead the safety model

SQLite cratelocal signal path

It does not upload your collection. It does not decide what is a good mix. It helps you narrow a large folder into candidates worth hearing together.

The Python backend, CLI, and React client use one structurally validated library database. The adjacent Evaluation database is optional and is created only by Evaluation workflows. Normal startup refuses incompatible legacy layouts and never migrates them automatically.

The Project Idea

A personal problem drives the project: a large local music folder can hide the next useful track, even when that track is already in your collection. dj-track-similarity tries to make that library easier to rediscover by combining tags, audio features, embeddings, text prompts, and optional personal classifiers.

The larger idea is DJ set dramaturgy. A set is not just a list of compatible tracks. It can have an opening, tension, release, chapters, and a destination. The app is meant to suggest candidates worth listening to while the DJ keeps the final musical decision.

This is a personal enthusiast project first. It does not claim expert ML or music-information-retrieval authority, and model output should be read as local ranking evidence, not truth. Read the project idea.

What you can do with it

Rediscover nearby tracks

Start from a familiar track and audition a ranked neighborhood from your own collection.

Search for a sound

Describe rhythm, texture, instruments, space, or energy when you do not have a reference track.

Collect a current set by hand

Add candidates one at a time, preview them, reorder by removing, and export as M3U or CSV.

Reuse your own criteria

Label a recurring personal concept and make it available as a CLASS library filter.

Normal path

The workflow stays local

Start with a database and a folder scan. Add model data when needed. Search and export previews after that. The app gives you ranked candidates. Final track decisions still happen by ear.

1. 01ScanMake the folder browsable without moving audio.
2. 02AnalyzePrepare the sound comparisons needed for your task.
3. 03SearchTurn tracks, words, or personal criteria into shortlists.
4. 04ExportTake the reviewed list into the next part of your workflow.

What the app reads

• Audio paths and file stats.
• Mutagen-readable tags: artist, title, album, genre, year, country, label, track number, BPM, key, and comment. Duration and format data come from the file rather than from a tag.
• Decoded audio when you run analysis, preview a track, or use maintenance helpers.

What the app writes by default

Most workflows write only local SQLite records and local reports. Scanning, Refresh Tags, analysis, search, preview, reset, clear, relocation preview, classifier scoring, and export do not modify source audio files.

The file-writing exceptions are explicit:

• MAEST genre tag apply writes the standard genre field in audio files.
• Audio Doctor apply repairs files reported as repairable. It is dry-run first, backs up each file before writing, verifies the result, and restores the backup when a check fails. It takes no confirmation phrase, so --apply writes as soon as the run reaches a repairable file.
• Audio Dedup deletes duplicate copies. The CLI makes the operator type APPLY DELETE. The browser reviewer asks a Yes / No question and its client supplies the phrase to the API itself.

Relocation apply is SQLite-only. It updates stored tracks.file_path values and does not move files.

Read-heavy by default

Search, preview, analysis, reset, current-set editing, and export avoid source-audio edits.

Explicit write paths

Genre apply, Audio Doctor apply, and Audio Dedup deletion are separate guarded flows.

Local artifacts

SQLite databases, reports, logs, and classifier files stay on disk.

Start here

• Quickstart: scan, serve the UI, analyze a first batch.
• Install: prerequisites, optional ML dependencies, frontend and docs builds.
• First library: build the SQLite library and understand scan behavior.
• First analysis: choose analysis by the result you want.
• Migrate and reanalyze SONARA storage: preview and back up structural changes, then reanalyze only when needed.
• User guide: daily UI work.
• Workflows: DJ task recipes.
• Concepts: scores, models, safety, and routing.
• Tools and scripts covers helper docs, including Rhythm Lab and the maintenance/report tools.
• Reference: CLI, API, config, database, analysis, and UI facts.
• Help: symptoms, FAQ, and known limits.

The interface mixes Russian and English

Most panel headings, buttons, and tooltips in the browser are Russian; model names, tab labels, and mode names are English. The documentation names every control in English regardless. UI language maps one to the other, control by control. Read it before following any page that tells you to press something.