XML Export

XML structure

A minimal Rekordbox XML file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<DJ_PLAYLISTS Version="1.0.0">
  <PRODUCT Name="rekordbox" Version="7.2.10" Company="AlphaTheta"/>
  <COLLECTION Entries="12">
    <TRACK TrackID="1" Name="Track Title" Artist="Artist Name"
           Genre="Deep House" Comments="Great track" Rating="204"
           Location="file://localhost/Users/.../track.flac"
           Tonality="Am" AverageBpm="124.00" Colour="0x25FDE9"/>
  </COLLECTION>
  <PLAYLISTS>
    <NODE Type="0" Name="ROOT" Count="1">
      <NODE Type="1" Name="My Set" Entries="12" KeyType="0">
        <TRACK Key="1"/>
      </NODE>
    </NODE>
  </PLAYLISTS>
</DJ_PLAYLISTS>

---

What reklawdbox exports

Editable fields (actively written by write_xml): Genre, Comments, Rating (1-5), Colour, Label, Year, Album.

Pass-through fields (read from DB, included in export): title, artist, album, remixer, label, year, key, BPM, file location, file kind, bit rate, sample rate, play count, date added, total time.

Omitted fields (not included in export): Composer, Grouping, Mix, Size, DiscNumber, TrackNumber.

Playlists are included when write_xml is called with the playlists parameter.

Caution

Beat grids (TEMPO) and cue points (POSITION_MARK) are not included in the export. They’re preserved in the Rekordbox database and unaffected by reimport.

---

Importing into Rekordbox

An export can contain staged track metadata, playlist name and order, or both. Use each applicable handoff independently:

What you exported	Handoff and verification
Track metadata	Set Imported Library, then use rekordbox xml → All Tracks → Import To Collection. Verify the intended field values.
Playlist name and order	Use rekordbox xml → Playlists, then drag/import the generated playlist under Rekordbox Playlists. Verify its name, track count, first and last tracks, and representative order.

Playlist exports are produced by Set Building, Pool Building, and Chapter Set Planning.

Apply staged track metadata

1. Add XML to Rekordbox — Open Preferences → Advanced → rekordbox xml → Imported Library → Browse → select the exported XML file.

2. Verify in the XML view — In the sidebar, click the “Display rekordbox xml” icon. Browse the imported tracks under “All Tracks” and check that the metadata looks correct before importing.

3. Import into collection — Once satisfied, select all tracks (Cmd+A), right-click → Import To Collection. When prompted “Do you want to load information in the tag of the library being imported?”, click Yes (tick “Don’t ask me again” for bulk imports).

Tip

On the confirmation dialog, tick “Don’t ask me again” if you’re importing a large batch — it applies to every track that already exists in your collection.

Import a playlist and its order

Use the playlist path in Rekordbox for the exported playlist name and order:

1. Keep the XML file available — Note the path reported by write_xml. Do not move or delete the file until the imported playlist is verified.
2. Open the XML browser — If rekordbox xml is hidden, enable it under Preferences → View → Layout → Media Browser. Under Preferences → Advanced → Database → rekordbox xml, set Imported Library to the exported XML file.
3. Preview the generated playlist — Expand rekordbox xml → Playlists, select only the generated playlist, and check its name and track order before importing it.
4. Import the playlist — Drag that playlist to the desired location under Rekordbox Playlists. If the current UI offers Playlist → Import Playlist for the selected rekordbox xml playlist, that action can be used instead.
5. Verify before cleanup — In the imported playlist, confirm the track count, the first and last tracks, and representative transitions through the order. Keep the XML file until these checks pass.

This is not the metadata-import path. rekordbox xml → All Tracks → Import To Collection applies staged track metadata; importing the playlist does not. Complete that separate flow when the XML also contains staged metadata changes.

The XML export is the agent’s stopping point. Report the path, then wait for the user to complete and confirm these Rekordbox steps. Do not say the playlist is installed before that confirmation.

---

What survives a round-trip

Preserved: Genre, Comments, Rating, Colour, Label, Year, title, artist, album, remixer, key, BPM, playlist structure.

Not included: Cue points, beat grids, My Tags, Hot Cue Banks, phrase analysis, smart playlist criteria, waveform data (ANLZ files). These remain in the Rekordbox database — reimport doesn’t touch them.

---

Rating values

Rekordbox maps stars to 0/51/102/153/204/255. reklawdbox converts automatically — you specify 1-5 in tool calls.

---

Track colors

Pass one of these eight canonical color names to update_tracks (matching is case-insensitive). reklawdbox validates and canonicalizes the name, then serializes the corresponding hex value into Rekordbox XML. Hex strings are XML output representations, not accepted tool inputs.

Color name	XML hex
Blue	0x0000FF
Green	0x00FF00
Lemon	0xFFFF00
Orange	0xFFA500
Red	0xFF0000
Rose	0xFF007F
Turquoise	0x25FDE9
Violet	0x660099

---

Key format

Rekordbox XML uses classic notation (Am, Bb, F#m). Camelot is display-only in the UI. reklawdbox converts automatically.

---

Backup behavior

Every write_xml call automatically backs up your Rekordbox database files before writing. The backup is a compressed archive of master.db and related allowlisted files from the same effective database directory, stored in ~/Music/rekordbox-backups/. When REKORDBOX_DB_PATH selects a nonstandard library, both the server’s read-only connection and this backup use that exact resolved file. Up to 20 pre-operation backups are kept; older ones are rotated out.

The built-in backup succeeds only after its archive is created and moved into place. If its path is invalid or any archive step fails, staged changes are restored for retry and the export is blocked — the XML file is not created. These archives cover the database-related allowlist, not your audio files, and they are not a guaranteed online snapshot while Rekordbox is changing the database. Close Rekordbox before exporting for the strongest backup consistency.

You can also manage backups manually with reklawdbox backup — see CLI Commands.

To use a custom backup script instead of the built-in one, set REKLAWDBOX_BACKUP_SCRIPT in your environment. It receives --pre-op first and the effective path in its child REKORDBOX_DB_PATH. A zero exit is trusted as that operator-supplied script’s success attestation; reklawdbox does not inspect an arbitrary script’s archive. A missing script, launch failure, or nonzero exit blocks XML export and keeps the staged changes available for retry. See Environment Variables.

XML files are written to ~/reklawdbox-exports/ by default.

---

Notes

• Location paths use file://localhost/ with URL encoding — handled automatically.
• Collection count (Entries) must match the actual <TRACK> count or Rekordbox rejects the file.
• Import is additive only — never deletes tracks from your collection.
• Genre is free text — no predefined list in Rekordbox.