Skip to content

JSON formats

With --json, a command prints exactly one JSON document on standard output and nothing else. Questions and progress go to standard error. An error is a JSON error document on standard error.

Every document starts with format, which names it, and version. A new version means an incompatible change, such as a field removed, renamed or given another meaning. New fields can appear without a new version, so a client should ignore the fields it does not know.

Format Version Printed by
tunedex-plan 3 scan, relocate, fix, enrich, dupes --merge, write-tags, rename, import mixxx, import beets, export m3u, export mixxx
tunedex-status 1 status
tunedex-tracks 1 list
tunedex-track 1 show
tunedex-playlists 1 playlists
tunedex-dupes 1 dupes
tunedex-snapshots 1 snapshot list
tunedex-restore 1 snapshot restore

Conventions in every format:

  • Times are integer microseconds (duration_us, start_us).
  • Dates are ISO 8601 text: 2026-10-30, and 2026-10-30T19:39:27+00:00 with a time.
  • Paths are absolute paths on this computer, as text.
  • Unknown values are null; a field is never left out.

tunedex-plan

Version 3. Every command that changes something prints its plan. Without --apply this is a dry run and result is null. With --apply, the same document also carries the result.

{
  "format": "tunedex-plan",
  "version": 3,
  "target": "m3u-568b52ce5ecb",
  "title": "export m3u to /home/ana/playlists",
  "location": "/home/ana/playlists",
  "empty": false,
  "tracks": [],
  "refreshed": 0,
  "rebased": 0,
  "playlists": [
    {
      "change": "added",
      "path": ["Sets", "Friday"],
      "kind": "playlist",
      "entries_added": ["/home/ana/Music/techno/a.mp3", "/home/ana/Music/techno/b.mp3"],
      "entries_removed": [],
      "reordered": false,
      "renamed_from": null
    }
  ],
  "untouched_playlists": 0,
  "files": [
    {
      "path": "/home/ana/playlists/Sets/Friday.m3u8",
      "action": "create",
      "bytes": 292,
      "sha256_before": null,
      "sha256_after": "834823acbe34b22a240548e1e51a87b08fb431e2a4cd44d6ed9930c5e2a9808e",
      "description": "create playlist 'Friday' (2 entries)"
    }
  ],
  "trash": [],
  "losses": [
    {
      "kind": "field:bpm",
      "description": "bpm is not stored",
      "count": 2,
      "examples": ["Velk - Rise", "Arno - Fall"]
    }
  ],
  "warnings": [],
  "conflicts": [],
  "tags": [],
  "snapshot_bytes": 0,
  "result": {
    "status": "applied",
    "snapshot": "000001-20261030T193927Z",
    "files_written": 1,
    "operations_applied": 0,
    "files_trashed": 0,
    "files_renamed": 0,
    "warnings": []
  }
}
Field Type Meaning
target string What the plan changes: library for the tunedex library, tags for the tags of audio files, renames for file names, or <adapter>-<12 hex digits> for an export target. Snapshots are kept per target.
title string A one-line description of the plan.
location string or null The folder or file the plan writes to; null for the library.
empty boolean true when there is nothing to do.
tracks array of track changes Tracks added, updated, moved, missing, present again or merged. A renamed file is a moved track.
refreshed integer Files whose recorded state was refreshed without any field change (scans only).
rebased integer Tracks whose import base was updated without any field change (imports only).
playlists array of playlist changes Folders, playlists and smartlists added, updated or removed.
untouched_playlists integer Playlists in the target that the library does not have. They are left alone (exports only).
files array of file changes Every file the apply would write (exports only).
trash array Audio files the apply would move to the system trash (dupes --merge): path and bytes.
losses array of losses What the target cannot keep.
warnings array of strings Things to know before applying.
conflicts array of conflicts Fields edited in tunedex whose tag also changed in the file (scans). tunedex's value is kept.
tags array of tag writes Audio files whose tags the apply would write (write-tags only).
snapshot_bytes integer About how much the tag snapshot takes, in bytes (write-tags only; 0 otherwise).
result result or null What the apply did; null in a dry run.

Track change

Field Type Meaning
change string added, updated, moved, missing, present or merged.
track_id string or null The track's id; null for a track the plan adds.
path string The track's path, after the change.
old_path string or null For a moved track, the path before.
merged_into string or null For a merged track, the path of the track it was merged into.
name string How the track is shown: artist - title, or the file name.
fields array Each changed field: field, before, after, and by, the fix, rule or source that made the change (or null). For an added track, every field it has, from null.

Tag write

{
  "track_id": "0b5a4ba6-41a4-4f06-9a59-4d8b2b5c46a1",
  "path": "/home/ana/Music/dl/galaxy.mp3",
  "name": "Sam Paganini - Galaxy",
  "fields": [
    {"field": "title", "before": "Galaxy [www.slider.kz]", "after": "Galaxy", "by": null},
    {"field": "comment", "before": "00000EC8 00000EC8", "after": null, "by": null}
  ]
}
Field Type Meaning
track_id, path, name strings The track and its file.
fields array Each field to write: field, before (the value in the file now) and after (the library's value, written to the file). An after of null removes the field from the file. by is always null.

Playlist change

Field Type Meaning
change string added, updated or removed.
path array of strings The names from the top folder down to this node.
kind string folder, playlist or smartlist.
entries_added, entries_removed arrays of strings Paths of the tracks added to or removed from the playlist.
reordered boolean Whether the order of the entries changed.
renamed_from array of strings or null The previous path of a renamed node.

File change

Field Type Meaning
path string The file to write.
action string create or update.
bytes integer The size of the new content.
sha256_before string or null The hash of the file when the plan was made; null for a new file. The apply stops with stale_target if it no longer matches.
sha256_after string The hash of the new content.
description string What the change is, in words.

Loss

Field Type Meaning
kind string What is lost, such as field:bpm or tracks-outside-playlists.
description string The loss in words.
count integer How many tracks or items it affects.
examples array of strings A few of them, by name.

Conflict

Field Type Meaning
track_id, path, name strings The track.
field string The field.
library_value any The value in tunedex, which is kept.
file_value any The value now in the file's tags.

Result

Field Type Meaning
status string applied; declined when the confirmation was refused; nothing when the plan was empty.
snapshot string or null The snapshot taken before writing.
files_written integer Files written to the target; for write-tags, the audio files whose tags were written.
operations_applied integer Changes written to the library.
files_trashed integer Audio files moved to the system trash.
files_renamed integer Audio files renamed (rename).
warnings array of strings Problems that did not stop the apply, such as a file that could not be trashed.

tunedex-status

Version 1. A summary of the library.

{
  "format": "tunedex-status",
  "version": 1,
  "home": "/home/ana/.local/share/tunedex",
  "library_exists": true,
  "tracks": 4,
  "missing": 0,
  "playlists": 2,
  "smartlists": 0,
  "folders": 1,
  "sources": [{"name": "mixxx", "imported_at": "2026-10-30T19:20:02+00:00"}],
  "snapshots": [
    {
      "target": "library",
      "id": "000003-20261030T193927Z",
      "created_at": "2026-10-30T19:39:27+00:00",
      "reason": "scan /home/ana/Music"
    }
  ],
  "duplicate_groups": 1
}
Field Type Meaning
home string The home directory in use.
library_exists boolean false when nothing was applied to this home yet. The counts are then 0.
tracks, missing integers Tracks in the library, and how many of their files are not on this computer.
playlists, smartlists, folders integers Nodes in the playlist tree.
sources array Each source imported from, with name and imported_at.
snapshots array The newest snapshot of each target: target, id, created_at, reason.
duplicate_groups integer Groups that tunedex dupes would report.

tunedex-tracks

Version 1. The tracks that match the filters, by artist and title.

{
  "format": "tunedex-tracks",
  "version": 1,
  "tracks": [
    {
      "path_origin": "/home/ana/Music/techno/a.mp3",
      "id": "50a8cc13-633d-4e86-b983-5d263d6c0c09",
      "path": "/home/ana/Music/techno/a.mp3",
      "title": "Rise",
      "artist": "Velk",
      "genre": "Techno",
      "bpm": 132.0,
      "key": {"open_key": "8m", "musical": "Bbm"},
      "duration_us": 386856000,
      "bitrate": 320,
      "file_format": "mp3",
      "tags": [],
      "cues": [],
      "beatgrid": null,
      "unmapped": {}
    }
  ]
}
Field Type Meaning
tracks array of tracks The matching tracks.

The example is shortened: every track field is always present.

Track

Field Type Meaning
id string A stable UUID, assigned on first import. It never changes, even when the file moves.
path string The normalized path, used to recognize the same file across imports.
path_origin string The path exactly as the source gave it.
title, artist, album, album_artist, original_artist, genre, composer, producer, lyricist, remixer, mix, label, grouping, comment, extra1, extra2 string or null Text tags.
year, track_number, disc_number integer or null
bpm number or null Beats per minute, as stored.
key object or null The musical key in both notations: open_key (1m–12m, 1d–12d) and musical (Am, C, ...).
key_original string or null The key as the source wrote it.
rating integer or null 0 to 5.
color string or null #rrggbb.
play_count integer or null
date_added, date_modified, release_date string or null Dates.
last_played string or null Date and time.
duration_us integer or null Length in microseconds.
bitrate, sample_rate integer or null In kbit/s and Hz.
file_format string or null mp3, flac, wav, aiff, m4a, ...
energy, danceability, happiness, popularity integer or null 0 to 10.
tags array of strings Free tags.
cues array Cues and loops: kind (hot, memory or loop), start_us, slot (the hot-cue pad, or null), name, color, end_us (loops only), active, unmapped.
beatgrid object or null markers: each with position_us, bpm, and beat, its place in the bar (1–4). Several markers mean tempo changes.
unmapped object Fields a source has that tunedex does not model. They are kept so they can be written back.

tunedex-track

Version 1. One track, with where it is used.

{
  "format": "tunedex-track",
  "version": 1,
  "track": {"id": "50a8cc13-633d-4e86-b983-5d263d6c0c09", "path": "/home/ana/Music/techno/a.mp3"},
  "present": true,
  "playlists": ["Sets/Friday"],
  "sources": ["mixxx"]
}
Field Type Meaning
track track Every field of the track (shortened in the example).
present boolean Whether the file is on this computer.
playlists array of strings Paths of the playlists and smartlists that hold the track, in tree order.
sources array of strings The sources it was imported from, sorted.

tunedex-playlists

Version 1. The playlist tree, depth first.

{
  "format": "tunedex-playlists",
  "version": 1,
  "nodes": [
    {"name": "Sets", "kind": "folder", "depth": 0, "tracks": null, "path": "Sets"},
    {"name": "Friday", "kind": "playlist", "depth": 1, "tracks": 2, "path": "Sets/Friday"},
    {"name": "Saturday", "kind": "playlist", "depth": 1, "tracks": 1, "path": "Sets/Saturday"}
  ]
}
Field Type Meaning
nodes array Each folder, playlist and smartlist, in tree order.
nodes[].kind string folder, playlist or smartlist.
nodes[].depth integer 0 for the top level.
nodes[].tracks integer or null Tracks in a playlist or selected by a smartlist; null for folders.
nodes[].path string The path that --playlist takes, such as Sets/Friday.

tunedex-dupes

Version 1. Groups of tracks that are the same song. The suggested track to keep comes first.

{
  "format": "tunedex-dupes",
  "version": 1,
  "groups": [
    {
      "name": "Arno - Glow",
      "reason": "playlists",
      "tracks": [
        {
          "track_id": "2bbb4707-8d7d-4e1a-8200-7ebfa80f7371",
          "path": "/home/ana/Music/house/c.mp3",
          "format": "mp3",
          "bitrate": 320,
          "duration_us": 301000000,
          "cues": 0,
          "playlists": 1,
          "present": true,
          "suggested": true
        },
        {
          "track_id": "3cade962-60b1-4d52-afde-a4b5f88881e9",
          "path": "/home/ana/Music/house/c copy.mp3",
          "format": "mp3",
          "bitrate": 320,
          "duration_us": 301000000,
          "cues": 0,
          "playlists": 0,
          "present": true,
          "suggested": false
        }
      ]
    }
  ]
}
Field Type Meaning
groups[].name string The song, as artist - title.
groups[].reason string Why the first track is suggested over the second: file present, lossless, bitrate, cues, beat grid, playlists, oldest or path.
groups[].tracks array The tracks, best first. Each has track_id, path, format, bitrate, duration_us, cues (a count), playlists (a count), present and suggested.

tunedex-snapshots

Version 1. The snapshots of every target, newest first within each target.

{
  "format": "tunedex-snapshots",
  "version": 1,
  "snapshots": [
    {
      "target": "m3u-568b52ce5ecb",
      "id": "000001-20261030T193927Z",
      "created_at": "2026-10-30T19:39:27.271558+00:00",
      "reason": "export m3u to /home/ana/playlists",
      "tunedex_version": "0.1.0",
      "files": ["/home/ana/playlists/Sets/Friday.m3u8", "/home/ana/playlists/Sets/Saturday.m3u8"]
    }
  ]
}
Field Type Meaning
snapshots[].target string The target the snapshot belongs to, as in a plan.
snapshots[].id string The id that snapshot restore takes.
snapshots[].created_at string When it was taken.
snapshots[].reason string The plan it was taken before.
snapshots[].tunedex_version string The tunedex version that took it.
snapshots[].files array of strings The files it holds.

tunedex-restore

Version 1. What restoring a snapshot does. Without --apply, result is left out.

{
  "format": "tunedex-restore",
  "version": 1,
  "target": "m3u-568b52ce5ecb",
  "snapshot": "000001-20261030T193927Z",
  "files": [
    {"path": "/home/ana/playlists/Sets/Friday.m3u8", "action": "put_back"},
    {"path": "/home/ana/playlists/Sets/New.m3u8", "action": "remove"}
  ],
  "renames": [],
  "result": {"status": "restored", "pre_restore": "000002-20261030T194502Z"}
}
Field Type Meaning
target, snapshot strings What is restored.
files[].action string put_back: the file returns to its content in the snapshot. remove: the file did not exist then and is deleted. For a tags snapshot, put_back rebuilds the file from its tags in the snapshot and its current audio.
renames array For a renames snapshot, each file renamed back first: from (its name now) and to (its name in the snapshot). Empty for other targets.
result object Only with --apply. status is restored or declined. On restored, pre_restore is the snapshot taken just before, so the restore can itself be undone.