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 and CLI now use a greenfield schema-v7 bundle with Core plus mandatory Artifacts and optional Evaluation. They do not migrate older schemas. The React frontend port is deferred, so use CLI or direct API workflows for the current v7 contract.

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.

Draft a musical route

Turn a few anchors into an editable sequence with a chosen energy, diversity, and tempo direction.

Reuse your own criteria

Label a recurring personal concept and make it available as a library filter or gentle SET preference.

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 such as artist, title, album, genre, year, BPM, key, label, catalog number, comments, ISRC, duration, and format data.
• 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 only after dry-run state exists and exact confirmation is typed.
• Audio Dedup apply deletes confirmed duplicate candidates only after exact confirmation is typed.

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

Read-heavy by default

Search, SET, preview, analysis, reset, and export avoid source-audio edits.

Explicit write paths

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

Local artifacts

SQLite databases, reports, logs, indexes, 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.
• Prepare and rebuild a SONARA release: back up and activate the four current outputs before reanalysis.
• 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.