Files & System
File tag tools
Section titled “File tag tools”Read and write native metadata tags (ID3v2, Vorbis Comment, RIFF INFO, MP4/iTunes) on audio files. Supports FLAC, MP3, WAV, M4A, AAC, AIFF.
read_file_tags
Section titled “read_file_tags”Read metadata tags from audio files.
| Parameter | Type | Required | Description |
|---|---|---|---|
paths | string[] | Explicit file paths | |
track_ids | string[] | Resolve paths from Rekordbox track IDs | |
directory | string | Scan a directory for audio files | |
glob | string | Glob filter within directory (default: all audio) | |
recursive | boolean | Scan subdirectories (default: false) | |
fields | string[] | Return only these tag fields (default: all) | |
include_cover_art | boolean | Include cover art metadata (default: false) | |
limit | integer | Max files to read (default: 200, max: 2000) |
Provide exactly one of paths, track_ids, or directory. Passing multiple selectors or none returns an error.
write_file_tags
Section titled “write_file_tags”Write or delete metadata tags on audio files.
| Parameter | Type | Required | Description |
|---|---|---|---|
writes | array | yes | Array of write operations |
dry_run | boolean | Preview changes without writing (default: false) |
Each write entry:
| Field | Type | Required | Description |
|---|---|---|---|
path | string | yes | Path to audio file |
tags | object | yes | Field names mapped to values, or null to delete |
wav_targets | string[] | WAV only: "id3v2", "riff_info" (default: both) | |
comment_mode | string | How to handle existing comments |
Comment merge modes:
| Mode | Behavior |
|---|---|
replace | Overwrite existing comment (default) |
prepend | Insert before existing, separated by | |
append | Insert after existing, separated by | |
extract_cover_art
Section titled “extract_cover_art”Extract embedded cover art from an audio file and save it to disk.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Path to audio file |
output_path | string | Save location (default: cover.{ext} in same directory) | |
picture_type | string | Which art to extract (default: "front_cover") |
embed_cover_art
Section titled “embed_cover_art”Embed cover art into one or more audio files.
| Parameter | Type | Required | Description |
|---|---|---|---|
image_path | string | yes | Path to image file (JPEG or PNG) |
targets | string[] | yes | Audio files to embed art into |
picture_type | string | Picture type (default: "front_cover") |
Library health
Section titled “Library health”Scan the Rekordbox library for structural problems: broken file links, orphan files on disk, playlist gaps, and duplicate tracks.
scan_broken_links
Section titled “scan_broken_links”Scan for tracks with missing audio files on disk. Optionally suggests relocated files by case-insensitive filename matching across content roots.
| Parameter | Type | Required | Description |
|---|---|---|---|
path_prefix | string | Scope to tracks whose file path starts with this prefix | |
suggest_relocations | boolean | Attempt case-insensitive filename matching for relocations (default: true) | |
limit | integer | Max broken links to report (default: 200) | |
offset | integer | Offset for pagination |
scan_orphan_files
Section titled “scan_orphan_files”Find audio files on disk not imported into Rekordbox. Compares filesystem contents against the database for each content root.
| Parameter | Type | Required | Description |
|---|---|---|---|
path_prefix | string | Directory to scan (default: content roots from library) | |
limit | integer | Max orphan files to report (default: 200) |
scan_playlist_coverage
Section titled “scan_playlist_coverage”Find tracks not assigned to any playlist. Supports all search filters for scoping.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Search query matching title or artist | |
artist | string | Filter by artist name (partial match) | |
genre | string | Filter by genre name (partial match) | |
rating_min | integer | Minimum star rating (1—5) | |
bpm_min | number | Minimum BPM | |
bpm_max | number | Maximum BPM | |
key | string | Filter by musical key (e.g. "Am", "Cm") | |
has_genre | boolean | Filter by whether track has a genre set | |
has_label | boolean | Filter by whether track has a label set | |
year_zero | boolean | Filter to tracks with year = 0 (unset) | |
label | string | Filter by label name (partial match) | |
path | string | Filter by file path/folder (substring match) | |
path_prefix | string | Filter to tracks whose file path starts with this prefix | |
added_after | string | Only tracks added on or after this ISO date | |
added_before | string | Only tracks added on or before this ISO date | |
has_unknown_genre | boolean | Filter to tracks with a non-canonical genre (not in taxonomy and no known alias) | |
limit | integer | Max uncovered tracks to return (default: 200) | |
offset | integer | Offset for pagination |
scan_duplicates
Section titled “scan_duplicates”Detect duplicate tracks by metadata (artist+title) or exact file hash (SHA-256). Each group includes a suggested_keep recommendation based on audio quality.
| Parameter | Type | Required | Description |
|---|---|---|---|
detection_level | string | "metadata" (default) or "exact" (SHA-256 hash) | |
path_prefix | string | Scope to tracks whose file path starts with this prefix | |
limit | integer | Max duplicate groups to report (default: 50) |
System tools
Section titled “System tools”audit_state
Section titled “audit_state”Collection audit tool. The operation field determines the action.
Operation: scan
Section titled “Operation: scan”Scan a directory tree for convention violations.
| Parameter | Type | Required | Description |
|---|---|---|---|
operation | string | yes | "scan" |
scope | string | yes | Directory path to audit (must not be empty or root /) |
revalidate | boolean | Re-read all files including unchanged (default: false) | |
skip_issue_types | string[] | Issue types to exclude (e.g., ["GENRE_SET"]) |
Detects: empty fields, WAV tag drift, filename convention violations, and imported file protection warnings.
Operation: query_issues
Section titled “Operation: query_issues”Query detected issues from a previous scan.
| Parameter | Type | Required | Description |
|---|---|---|---|
operation | string | yes | "query_issues" |
scope | string | yes | Directory path prefix to filter (must not be empty or root /) |
status | string | "open", "resolved", "accepted", "deferred" | |
issue_type | string | Filter by issue type | |
limit | integer | Max results (default: 100) | |
offset | integer | Pagination offset (default: 0) |
Operation: resolve_issues
Section titled “Operation: resolve_issues”Mark issues as resolved with a resolution type.
| Parameter | Type | Required | Description |
|---|---|---|---|
operation | string | yes | "resolve_issues" |
issue_ids | integer[] | yes | Issue IDs to resolve |
resolution | string | yes | "accepted_as_is", "wont_fix", "deferred" |
note | string | Optional comment |
Operation: get_summary
Section titled “Operation: get_summary”Get an audit summary with issue counts by type and status.
| Parameter | Type | Required | Description |
|---|---|---|---|
operation | string | yes | "get_summary" |
scope | string | yes | Directory path prefix (must not be empty or root /) |
clear_caches no params
Section titled “clear_caches ”Clear all internal caches (enrichment, audio analysis, audit state) and all staged metadata changes. Preserves Discogs broker session.
Get workflow guides with step-by-step instructions.
| Parameter | Type | Required | Description |
|---|---|---|---|
topic | string | "genre", "genre audit", "set", "pool", "chapter", "audit", "import", "metadata" (aliases: "label", "year", "album"), "health" — or omit for all |