Files & System

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`

Read metadata tags from audio files.

Parameter	Type	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`

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	Values	Item values	Description
`path`	string	yes			Path to audio file
`tags`	object	yes			Field names mapped to values, or `null` to delete
`wav_targets`	string[]			`["id3v2", "riff_info"]`	WAV tag layers (default: both)
`comment_mode`	string		`["replace", "prepend", "append"]`		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 `\|`

For WAV dry runs, each requested tag layer is reported independently so its existing values and comment merges are visible before writing:

{
  "dry_run": true,
  "summary": { "files_previewed": 1, "files_failed": 0 },
  "results": [
    {
      "path": "/music/track.wav",
      "status": "preview",
      "changes": {
        "artist": { "old": "ID3 old", "new": "new" }
      },
      "changes_by_layer": {
        "id3v2": {
          "artist": { "old": "ID3 old", "new": "new" }
        },
        "riff_info": {
          "artist": { "old": "RIFF old", "new": "new" }
        }
      },
      "wav_targets": ["id3v2", "riff_info"]
    }
  ]
}

Every requested WAV layer appears in changes_by_layer, including as an empty object when it needs no changes. The legacy changes object remains for compatibility: it mirrors riff_info for a RIFF-only request and id3v2 for an ID3-only or both-layer request. Non-WAV previews omit changes_by_layer.

`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		Exact accepted picture type (default: `"front_cover"`); unknown values are rejected

Accepted cover-art picture types

Both cover-art tools accept these exact, case-sensitive, untrimmed values: other, icon, other_icon, front_cover, cover_front, back_cover, cover_back, leaflet, media, lead_artist, artist, conductor, band, composer, lyricist, recording_location, during_recording, during_performance, screen_capture, bright_fish, illustration, band_logo, and publisher_logo. cover_front and cover_back are compatibility aliases for the canonical front_cover and back_cover names. Unknown values are rejected. When a valid requested extraction type is absent, extraction falls back to the first embedded picture.

`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		Exact accepted picture type (default: `"front_cover"`); unknown values are rejected

Library health

Scan the Rekordbox library for structural problems: broken file links, orphan files on disk, playlist gaps, and duplicate tracks.

`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	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`

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`

Find tracks not assigned to any playlist. Supports all shared search filters for scoping.

Parameter	Type	Required	Description
`limit`	integer		Max uncovered tracks to return (default: `200`)
`offset`	integer		Offset for pagination

`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	Values	Description
`detection_level`	string	`["metadata", "exact"]`	Metadata matching (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`)
`offset`	integer		Offset into the stable ordered duplicate-group list (default: `0`)

Field	Type	Required	Description
`detection_level`	string	yes	Detection mode used for this scan
`group_count`	integer	yes	Duplicate groups returned on this page
`total_groups_found`	integer		Full-scope group count retained for exact-mode compatibility; use `page.total` for continuation
`total_duplicate_tracks`	integer	yes	Duplicate tracks in the returned page only
`duplicate_groups`	array	yes	Duplicate groups returned by this page
`page`	object	yes	Duplicate-group continuation metadata
`hash_errors_count`	integer		Files that could not be hashed in exact mode

Field	Type	Required	Description
`total`	integer	yes	Total duplicate groups in the selected scope
`returned`	integer	yes	Groups emitted by this page
`offset`	integer	yes	Requested group offset
`next_offset`	integer \| null	yes	Next group offset when more remain; `null` at the end
`has_more`	boolean	yes	Whether another group page remains

Continue with offset=page.next_offset while page.has_more is true. Exact mode rehashes the scope on each request, and both modes assume the library and files stay unchanged during traversal. Restart at zero after scope changes. limit=0 is a terminal no-op page.

System tools

`audit_state`

Collection audit tool. The operation field determines the action.

Operation: `scan`

Scan a directory tree for convention violations.

Parameter	Type	Required	Values	Description
`operation`	string	yes	`["scan", "query_issues", "resolve_issues", "get_summary"]`	This mode uses `"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.

The scan summary includes additive failed_reads. It counts files whose tags could not be read; those paths remain retryable and appear in warnings rather than being counted as successfully scanned or skipped unchanged. A result with total_open == 0 is not a clean or complete audit while failed_reads is nonzero: surface the affected paths, retry the scan, and report persistent failures as an incomplete audit.

Operation: `query_issues`

Query detected issues from a previous scan.

Parameter	Type	Required	Values	Description
`operation`	string	yes	`["scan", "query_issues", "resolve_issues", "get_summary"]`	This mode uses `"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`

Mark issues as resolved with a resolution type.

Parameter	Type	Required	Values	Description
`operation`	string	yes	`["scan", "query_issues", "resolve_issues", "get_summary"]`	This mode uses `"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`

Get an audit summary with issue counts by type and status.

Parameter	Type	Required	Values	Description
`operation`	string	yes	`["scan", "query_issues", "resolve_issues", "get_summary"]`	This mode uses `"get_summary"`
`scope`	string	yes		Directory path prefix (must not be empty or root `/`)

`clear_caches` no params

Clear all internal caches (enrichment, audio analysis, audit state) and all staged metadata changes. Preserves Discogs broker session.

`help`

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

Files & System

File tag tools

read_file_tags

write_file_tags

extract_cover_art

Accepted cover-art picture types

embed_cover_art

Library health

scan_broken_links

scan_orphan_files

scan_playlist_coverage

scan_duplicates

System tools

audit_state

Operation: scan

Operation: query_issues

Operation: resolve_issues

Operation: get_summary

clear_caches no params

help