Project guide

DJ Track Similarity helps you explore a local music collection when folders, tags, and memory are not enough. Start from a track you already know, a sound you can describe, or a rough set idea. The app turns that starting point into a smaller list worth listening to.

It does not decide which tracks are good or guarantee that two tracks will mix. Its job is to reduce the search space, show why a candidate appeared, and leave the musical decision to you.

The backend, CLI, and React client use one library database, with Evaluation only when needed. Normal startup refuses a legacy split layout and never rewrites it. The browser adds typed library, analysis, search, current set, classifier, and Lab workflows on top of the same API.

The interface itself mixes Russian and English labels while this documentation names every control in English. Keep UI language open beside any page that tells you to press something.

What you can get from it

Your situation	Start with	Result
You remember one useful track	SIMILARITY or SONARA tab	A ranked list of nearby candidates to preview
You can describe the sound without naming a track	PROMPT tab, CLAP or MuQ-MuLan	A shortlist matched to an audible description
You have useful candidates to collect	Current Set	An editable working list for preview and export
You want a broad pool for later listening	Filters, seeds, or text search	A crate that you can export as CSV or M3U
You repeatedly judge tracks by a personal idea	Rhythm Lab classifier	A reusable per-track score for CLASS filtering
You want to compare how each model ranks one reference	LAB tab	Six model groups side by side for one seed
You suspect duplicate files	Audio Dedup	A report you review before anything is deleted
You want online metadata for a track list	Audio Online	One XLSX with a column block per provider

Use this guide to choose the shortest route from your current idea to one of those results. Exact CLI, API, storage, and model details remain available in the reference section.

If you are new

1. Read Install.
2. Run Quickstart.
3. Build a database with First library.
4. Add model data with First analysis.
5. Make a first shortlist with Search with seed tracks or Text search.
6. Preview the results by ear before adding them to a crate or the current set.

If you want to prepare music

• Use Find compatible tracks when you have one or more reference tracks.
• Use Build crates when you want a listening pool rather than a final order.
• Use Text search when you know the sound but not the seed.

If you want to understand the signals

• Project idea explains the local-first DJ set dramaturgy goal and the author's modest scope.
• Features, embeddings, and tags explains what each stored signal means.
• Similarity scores explains why MERT, MuQ, MuQ-MuLan, SONARA, CLAP, and Audio Dedup scores should not be mixed casually.
• Classifiers and Rhythm Lab explains local classifier profiles and promoted scores.
• Local-first safety lists every path that can write to an audio file.

If you are maintaining a library

• Maintain library gives a safe routine.
• Analyze library explains reset and intentional reanalysis.
• Tags and audio writes lists the exact file-writing paths.
• Audio Doctor covers dry-run-first repair.
• Audio Dedup covers report-first duplicate checks.
• Optimize database covers SQLite maintenance with backup.
• Scripts covers the read-only QA, benchmark, and text-layer scripts.
• Audio Online covers online metadata enrichment.

If you need exact references

• CLI reference lists dj-sim commands and standalone tool commands.
• API reference lists endpoint families and important payloads.
• Configuration reference lists environment variables, ports, local artifacts, and build commands.
• SONARA integration describes collection, updates, and storage boundaries.
• UI controls reference lists ranges and defaults for common controls.
• Model citations and licenses lists the current upstream model and SONARA sources.

Current docs build command

Run this from an activated environment with Node dependencies installed:

cd docs\dj-track-similarity
npm run check

npm run check runs strict Vale style checking for README.md and the VitePress Markdown tree, then builds the static docs into site/.