Enrichment & Analysis

Enrichment tools

Look up metadata from Discogs, Beatport, MusicBrainz, and Bandcamp. Results are cached — subsequent calls return instantly unless force_refresh is set.

---

lookup_discogs

Look up a single track on Discogs. Returns genre, style, label, year, catalog number, and release metadata.

Parameter	Type	Required	Description
track_id	string		Track ID — auto-fills artist/title/album from library
artist	string		Artist name (required if no track_id)
title	string		Track title (required if no track_id)
album	string		Album/release title for more accurate matching
force_refresh	boolean		Bypass cache (default: false)

Note

If the session has expired, the response includes an auth_url — open it in a browser, approve access, and call again.

---

lookup_beatport

Look up a single track on Beatport. Returns genre, sub-genre, BPM, key, and label.

Parameter	Type	Required	Description
track_id	string		Track ID — auto-fills artist/title from library
artist	string		Artist name (required if no track_id)
title	string		Track title (required if no track_id)
force_refresh	boolean		Bypass cache (default: false)

---

lookup_musicbrainz

Look up a track on MusicBrainz for year/label data. Returns year from first-release-date and label from the best matching release. Results are cached.

Parameter	Type	Required	Description
track_id	string		Track ID — auto-fills artist/title from library
artist	string		Artist name (required if no track_id)
title	string		Track title (required if no track_id)
force_refresh	boolean		Bypass cache (default: false)

---

lookup_bandcamp

Look up a track on Bandcamp for year/label/tags data. Searches Bandcamp, then fetches the detail page for structured metadata. Particularly effective for underground/independent electronic music. Results are cached.

Parameter	Type	Required	Description
track_id	string		Track ID — auto-fills artist/title from library
artist	string		Artist name (required if no track_id)
title	string		Track title (required if no track_id)
force_refresh	boolean		Bypass cache (default: false)

---

enrich_tracks

Batch enrich tracks via Discogs/Beatport/Bandcamp. Accepts shared search filters to scope which tracks to enrich.

Parameter	Type	Required	Description
track_ids	string[]		Specific track IDs (highest priority selector)
playlist_id	string		Enrich tracks in this playlist
max_tracks	integer		Max tracks to enrich (default: 50)
offset	integer		Skip first N tracks in result set
providers	string[]		Providers: "discogs", "beatport", "bandcamp" (default: ["discogs"])
skip_cached	boolean		Skip already-cached tracks (default: true)
force_refresh	boolean		Bypass cache entirely (default: false)
concurrency	integer		Max concurrent enrichments (default: 4, max: 8)

Tip

For large libraries, use the CLI hydrate command instead — it runs unattended with progress bars and graceful shutdown. See CLI.

---

Audio analysis tools

stratum-dsp (compiled in): BPM, key, rhythm regularity. Essentia (optional): danceability, spectral centroid, loudness, onset rate, dynamic complexity. Results cached per track per backend.

---

analyze_track_audio

Analyze one track. Returns BPM, key, and (with Essentia) energy descriptors.

Parameter	Type	Required	Description
track_id	string	yes	Track ID
skip_cached	boolean		Skip if already cached (default: true)

Cache is keyed by file path and analysis schema version. A schema version bump invalidates stale entries.

---

analyze_audio_batch

Batch audio analysis. Accepts shared search filters to scope which tracks to analyze.

Parameter	Type	Required	Description
track_ids	string[]		Specific track IDs (highest priority selector)
playlist_id	string		Analyze tracks in this playlist
max_tracks	integer		Max tracks to analyze (default: 20)
offset	integer		Skip first N tracks in result set
skip_cached	boolean		Skip already-cached tracks (default: true)
concurrency	integer		Max concurrent analyses (default: cpus - 2, min: 1, max: 4)

---

setup_essentia no params

Install or validate Essentia in a local Python venv. Creates a venv at ~/.local/share/reklawdbox/essentia-venv/ if needed. Activation takes effect immediately — no server restart needed.