Known limits

Audience: Users deciding whether behavior is expected. Goal: List current boundaries without pretending they are bugs. Type: help

Local-first means local setup matters

The app depends on your local Python environment, FFmpeg, optional ML packages, GPU runtime, filesystem paths, and browser access to the backend.

Model analysis can be heavy

MAEST, MERT, MuQ, and CLAP require optional ML dependencies. Large libraries can take time and memory. MuQ runs on 24 kHz float32 audio and is currently limited to LAB Reference Compare, not SET, Hybrid, Audio Dedup, or classifier scoring. Use a small --limit first, then adjust device and batch sizes.

Scores are not probabilities

Search and SET scores are ranking signals. CLAP text scores, MERT seed scores, SET scores, Hybrid scores, and Audio Dedup thresholds should not be treated as one scale.

SET needs full coverage

Smart Set Builder requires SONARA plus MERT, MAEST, and CLAP embeddings. A partly analyzed library can browse and search in other tabs, but SET eligible counts will be low.

SONARA readiness uses exact active contracts

The library summary counts a SONARA Core row only when it matches the exact active core contract and release. Per-track coverage validates timeline, embedding, and fingerprint independently against their exact active contracts and the current track identity. The active release is one prepared four-contract set. A missing or stale output is not ready for that output.

Because v7 is a greenfield schema rather than an in-place migration target, the workflow prepares and activates the loaded release's four contracts before reanalyzing from a clean SONARA state. This full project set does not request SONARA tags or its genre model. See the SONARA v0.2.9 project contract.

Browser preview depends on files still existing

The database stores paths. If files move or disappear, preview fails until you rescan or relocate stored paths.

Native dialogs depend on local GUI support

Database and folder picker routes use local GUI support. If unavailable, type paths manually or use CLI commands.

Docs are built separately

The backend serves /docs/ only when docs/dj-track-similarity/site/ exists. Run npm run check from the docs folder to build it.