Classification & Staging
Genre tools
Section titled “Genre tools”get_genre_taxonomy no params
Section titled “get_genre_taxonomy ”Returns the canonical genre list and alias mappings. Use this tool as the authoritative current taxonomy rather than copying a genre count into clients.
suggest_normalizations
Section titled “suggest_normalizations”Analyze genres in your library and suggest normalizations to the canonical taxonomy.
| Parameter | Type | Required | Description |
|---|---|---|---|
min_count |
integer | Only include genres with at least this many tracks (default: 1) |
|
stage_aliases |
boolean | When true, auto-stage all alias normalizations in one call |
Returns three sections:
alias— known mappings from your genre strings to canonical genres (e.g., “Tech House” → “Tech House”)unknown— genres that don’t match any alias or canonical entrycanonical— genres that already match the taxonomy exactly
classify_tracks
Section titled “classify_tracks”Apply the genre decision tree to ungenred tracks using cached enrichment and audio evidence. Full mode requires fresh, valid Stratum and Essentia rows. Missing, stale, or invalid analyzer evidence produces Degraded mode, caps confidence at Low, requires review, and never auto-stages. High confidence additionally requires at least two independent source groups: Discogs, a distinct Rekordbox label, or audio. Discogs styles and a label copied from the same response remain one group. Current genre is only a low-confidence hint or unresolved-tie breaker. Cache-only — never triggers external calls.
| Parameter | Type | Required | Values | Item values | Description |
|---|---|---|---|---|---|
track_ids |
string[] | Specific track IDs to classify | |||
playlist_id |
string | Classify tracks in this playlist | |||
max_tracks |
integer | Max tracks (default: 50, max: 200) |
|||
offset |
integer | Skip first N tracks for pagination | |||
genre_overrides |
array | Remap genre strings before scoring (e.g., [{"from": "Melodic House & Techno", "to": "Deep Techno"}]) |
|||
format |
string | ["full", "compact", "summary", "dispatch"] |
Output format ("full" by default) |
||
auto_stage |
string[] | ["high", "medium", "low", "insufficient"] |
Auto-stage eligible Full-mode changes at these tiers; Degraded, confirmations, genre-less, and insufficient results are never staged |
Also accepts shared search filters. Enforces has_genre=false when using filters (bypassed when track_ids are provided explicitly).
Additive readiness output is stable across formats:
| Surface | Fields | Meaning |
|---|---|---|
| Full, compact, and dispatch track entries | mode, degraded_reasons |
mode is full or degraded; reasons are ordered Stratum first, then Essentia |
| Classification and audit summaries | by_mode, degraded_reasons |
Counts by mode and by missing/invalid backend reason |
Classification summary when auto_stage is requested |
auto_stage_skipped_degraded |
Otherwise-stageable Degraded recommendations blocked by the Full-only guard |
Staging output when auto_stage is requested |
staging.skipped_degraded |
The same blocked count alongside staged and total_pending |
Existing result and summary fields retain their meanings. The skipped count is not every Degraded result: it counts only a real recommendation that matched the requested confidence/action filters and was then rejected by mode.
audit_genres
Section titled “audit_genres”Verify existing genre tags against enrichment and audio evidence with the same Full/Degraded readiness contract. High/medium Full confirmations are counted and omitted by default. Degraded and Low/insufficient confirmations remain visible because readiness and confidence—not the confirm action—determine review eligibility. Cache-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
track_ids |
string[] | Specific track IDs to audit | |
playlist_id |
string | Audit tracks in this playlist | |
max_tracks |
integer | Max tracks (default: 50, max: 200) |
|
offset |
integer | Skip first N tracks for pagination | |
include_confirmed |
boolean | Include every confirmation (default: false); weak confirmations are always visible |
Also accepts shared search filters. Enforces has_genre=true when using filters (bypassed when track_ids are provided explicitly).
calibration_coverage
Section titled “calibration_coverage”Report per-genre readiness for audio-profile calibration from the verified playlist. It separates raw analyzer rows, complete Full-classification audio, missing/invalid analyzer evidence, scorable optional features, candidate prototypes, and persisted profile compatibility without recalibrating.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlist |
string | Playlist containing ear-verified tracks (default: genre_verified) |
Use this before calibrate_audio_profiles. Per-genre readiness_reason explains incomplete analyzer coverage, insufficient complete/scorable samples, candidate scoring, or stored readiness. profile_state.status is missing, fresh, training_changed, or incompatible. A training change requests recalibration but remains structurally usable; incompatible v1 profiles remain stored but are suppressed. BPM-only and partial rows count toward raw coverage, not v2 calibration evidence.
calibrate_audio_profiles
Section titled “calibrate_audio_profiles”Build Fisher-weighted audio prototypes from a playlist of ear-verified tracks and store them in the internal SQLite cache. These prototypes provide supplementary votes during classification.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlist |
string | Playlist containing ear-verified tracks (default: genre_verified) |
Run calibration_coverage first. Calibration requires fresh, valid Stratum and Essentia rows, then applies the existing scorable-feature and candidate checks. Missing, partial, unknown, and unscorable rows cannot train a v2 profile. A failed or empty recalibration leaves the compatible registry untouched; successful profile rows and classifier/analyzer/training metadata are replaced atomically.
backfill_labels
Section titled “backfill_labels”Auto-fill empty labels from enrichment caches (Discogs, MusicBrainz, and Bandcamp). Stages non-conflicting labels automatically; reports conflicts where the current label disagrees with enrichment.
| Parameter | Type | Required | Description |
|---|---|---|---|
dry_run |
boolean | Preview without staging (default: false) |
|
auto_enrich |
boolean | Fetch missing MusicBrainz and Bandcamp label keys, then re-scan with Discogs → MusicBrainz → Bandcamp precedence (default: false) |
|
max_conflicts |
integer | Cap on conflict entries in the response (default: 50) |
|
conflict_offset |
integer | Offset into the stable ordered conflict list (default: 0) |
| Field | Type | Required | Description |
|---|---|---|---|
summary |
object | yes | Full scan and label-fill counts |
staged |
integer | yes | Changes staged by this call |
total_pending |
integer | yes | Total changes currently staged in memory |
dry_run |
boolean | yes | Whether this call avoided staging |
conflicts |
array | yes | Conflict entries returned on this page |
conflict_page |
object | yes | Conflict continuation metadata |
conflicts_truncated |
boolean | Legacy alias present and true only when conflict_page.has_more is true |
|
auto_enriched |
integer | Total successful MusicBrainz and Bandcamp matches when auto_enrich=true |
|
auto_enriched_by_provider |
object | Successful-match counts for musicbrainz and bandcamp |
|
auto_enrichment |
object | Durable-write and failure report present whenever auto_enrich=true |
|
research_queue |
object | Remaining unlabeled-track research summary |
| Field | Type | Required | Description |
|---|---|---|---|
operation_failed |
boolean | yes | Whether lookup, persistence, worker, or writer failures occurred |
requested |
integer | yes | Provider keys selected for this invocation |
matched |
integer | yes | Successful provider matches, preserving the legacy counter meaning |
no_match |
integer | yes | Completed provider lookups with no result |
lookup_failed |
integer | yes | Provider lookups that failed and remain retryable |
cache_writes_succeeded |
integer | yes | Acknowledged durable positive and negative cache rows |
cache_writes_failed |
integer | yes | Expected cache rows prevented by serialization, queue, acknowledgement, writer-open, or SQLite failures |
serialization_failed |
integer | yes | Serialization failures, also counted in cache_writes_failed |
worker_failed |
integer | yes | Provider worker tasks that failed before a terminal lookup outcome |
writer_failed |
integer | yes | Cache-writer open, acknowledgement-receiver, or task failures |
by_provider |
object | yes | The same per-request counters keyed by bandcamp and musicbrainz |
failures |
array | yes | Up to 50 typed provider/key failure details with bounded summaries |
failures_truncated |
boolean | yes | Whether additional failure details were omitted after the 50-entry cap |
| Field | Type | Required | Description |
|---|---|---|---|
total |
integer | yes | Total conflicts in the stable ordered list |
returned |
integer | yes | Conflict entries emitted by this page |
offset |
integer | yes | Requested conflict offset |
next_offset |
integer | null | yes | Next conflict offset when more remain; null at the end |
has_more |
boolean | yes | Whether another conflict page remains |
Run the intended mutating or auto-enriching pass once. Retrieve later conflict
pages with dry_run=true, auto_enrich=false, and
conflict_offset=conflict_page.next_offset; this avoids repeating staging or
provider side effects. A zero page size and an offset beyond the end are
terminal no-ops.
When auto_enrich=true, inspect auto_enrichment.operation_failed and its
failure counters before treating the provider phase as complete. The legacy
auto_enriched fields count provider matches, while
cache_writes_succeeded counts acknowledged durable positive and negative
rows. Durable successes are re-scanned and may be staged even when another key
fails; use the typed failures to decide which provider/key lookups need a
retry. dry_run=true still suppresses staging only, so explicitly requested
auto-enrichment may write Reklawdbox-owned cache rows.
backfill_years
Section titled “backfill_years”Auto-fill missing years (year=0) from file tags, folder paths, and enrichment cache (Discogs/MusicBrainz/Bandcamp). Stages non-conflicting years automatically; reports conflicts where the current year disagrees with enrichment.
| Parameter | Type | Required | Description |
|---|---|---|---|
dry_run |
boolean | Preview without staging (default: false) |
|
auto_enrich |
boolean | Automatically enrich remaining year-zero tracks via Bandcamp and MusicBrainz before re-scanning (default: false) |
With auto_enrich=true, the response includes the same auto_enrichment
report described for backfill_labels. Successfully persisted MusicBrainz and
Bandcamp rows are re-scanned through the existing year cascade even when other
keys fail. Inspect the report before deciding that remaining gaps are genuine
no-matches rather than retryable lookup or persistence failures.
backfill_albums
Section titled “backfill_albums”Auto-fill empty album names from file tags, folder paths, and enrichment cache (Bandcamp/Discogs). Only fills tracks with no album set. Skips noise entries where the album matches the track title or artist name.
| Parameter | Type | Required | Description |
|---|---|---|---|
dry_run |
boolean | Preview without staging (default: false) |
|
auto_enrich |
boolean | Automatically enrich uncached tracks via Bandcamp before backfilling (default: false) |
With auto_enrich=true, the response includes the same auto_enrichment
report. Album auto-enrichment remains Bandcamp-only and best-effort, but a
provider match is not evidence of durable cache persistence: check
cache_writes_succeeded, operation_failed, and typed failures before
deciding whether a retry is needed.
Staging tools
Section titled “Staging tools”update_tracks ──> preview_changes ──> write_xml ──> verify in XML view ──> import │ clear_changes (undo)update_tracks
Section titled “update_tracks”Stage changes to track metadata. Held in memory until exported or cleared.
| Parameter | Type | Required | Description |
|---|---|---|---|
changes |
array | yes | Array of track change objects |
Each change object:
| Field | Type | Required | Description |
|---|---|---|---|
track_id |
string | yes | Track ID |
genre |
string | New genre | |
comments |
string | New comments | |
rating |
integer | Star rating (1-5) | |
color |
string | Color name | |
label |
string | Record label | |
year |
integer | Release year | |
album |
string | Album name |
You can stage changes for multiple tracks in one call. Calling update_tracks again for the same track merges fields — only the specified fields are overwritten, existing staged fields are preserved.
preview_changes
Section titled “preview_changes”Preview all staged changes, showing a diff from the current Rekordbox state.
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
track_ids |
string[] | Filter to specific track IDs (omit to show all staged; an empty array matches nothing) | ||
format |
string | ["full", "summary"] |
"full" (default) or "summary" (aggregate counts by field and genre) |
write_xml
Section titled “write_xml”Export staged changes to Rekordbox-compatible XML. Optionally includes playlists.
| Parameter | Type | Required | Description |
|---|---|---|---|
output_path |
string | Output path (default: ~/reklawdbox-exports/reklawdbox-{timestamp}.xml) |
|
playlists |
array | Optional playlist exports | |
skip_label_gate |
boolean | Set to true to acknowledge that label research is complete and bypass the label gate |
Each playlist object:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Playlist name |
track_ids |
string[] | yes | Track IDs in playlist order |
clear_changes
Section titled “clear_changes”Clear staged changes, either entirely or selectively by track or field.
| Parameter | Type | Required | Description |
|---|---|---|---|
track_ids |
string[] | Track IDs to clear (omit to clear all; an empty array clears nothing) | |
fields |
string[] | Fields to unstage: "genre", "comments", "rating", "color", "label", "year", "album" (omit to clear all fields on matched tracks) |