TrackRate user guide
Backup & Restore
Protect shared library data, database-specific state, and MCP changes with timestamped TrackRate backups.
7 questions
What does each file inside a TrackRate database store?
Each database has its own folder under db/<database-name>/. That separation is why the same audio file can have different ratings, hashtags, playlists, or enabled-folder state in two databases.
| File | Database-specific content | Manual manager | MCP snapshot |
|---|---|---|---|
tracks.json | Track fingerprints and the audio-file paths belonging to this database. | Yes | Yes |
ratings.json | Ratings, play counters, rating dates, and recent-play fields. | Yes | Yes |
tags.json | TrackRate hashtag assignments and the database’s tag index. | Yes | Yes |
playlists.json | Playlist names, membership, and saved track order. | Yes | Yes |
playlist-metadata.json | Playlist creation metadata such as timestamps. | Not a current card | Yes |
stats-cache.json | Cached library statistics used to avoid recalculating unchanged summaries. | Not a current card | Yes |
recipes.json | Saved recipe state used by generated or structured playback workflows. | Yes | Yes |
radio.json | Internet-radio stations saved for this database. | Not a current card | Yes |
disabled.json | Library folders disabled in this database without deleting their records. | Not a current card | Yes |
The current manual database toolbar exposes the five primary cards—ratings, playlists, tags, tracks, and recipes. The automatic MCP full snapshot iterates over every canonical file above in every existing database; files that have not been created yet are skipped.
How do I create and manage a manual TrackRate backup?
- Open Settings → Database → Backup & Restore.
- Use Back up shared files to copy
metadata.jsonandlyrics.wal. - Select a database from the database menu and choose its backup action to copy ratings, playlists, tags, tracks, and recipes.
- Use an individual card’s Back up now action when only one file type needs a restore point.
Global copies are written to backup/; per-database copies go to backup/<database-name>/. Every filename contains a timestamp, so several restore points can coexist. Each backup row provides Open, Restore, and Delete controls.
How does TrackRate automatically clean old backups?
The Auto-delete older than choices are 1 hour, 1 day, 1 week, 1 month, and Forever. The default is one day. The selected threshold applies to recognized timestamped backup files both in the global backup folder and in per-database subfolders.
These values are retention ages, not background timer frequencies. TrackRate checks and removes expired backup copies when the application starts. Choosing Forever disables age-based deletion. Cleanup never deletes the live metadata, lyrics, or database files—only backup copies older than the configured retention period.
What does the automatic MCP backup protect, and when does it run?
When Auto backup on MCP session is enabled, TrackRate creates one full safety snapshot immediately before the first mutating MCP tool in a logical MCP run. Read-only searches and inspection do not create a backup. Later writes in the same run reuse that restore point; it is not one backup or one undo record per edit.
The snapshot includes metadata.json, lyrics.wal, and every existing canonical database file listed above across every TrackRate database. If the required backup callback fails, the first mutating tool fails instead of continuing without the safety snapshot. The setting is enabled by default but can be changed in the MCP settings panel.
How do I restore a TrackRate backup safely?
Open Backup & Restore, locate the required timestamp and file type, and choose Restore. Restoration copies that backup over the current live file, so make a fresh backup of the present state first. For a multi-file incident, restore a coordinated set from the same timestamp rather than mixing unrelated versions.
The lyrics store is reinitialized after restoring a WAL backup. After restoring shared metadata or database JSON files, restart TrackRate so every in-memory view reloads from the restored files. Restoring TrackRate data does not overwrite the audio files themselves.
What is not included, and how do I move TrackRate to another computer?
The built-in data snapshot does not copy your audio library. It also does not currently include the album-art/ folder or annual history-YYYY.csv play-history files. For a complete migration, close TrackRate and copy the entire TrackRate user-data folder—including metadata.json, lyrics.wal, db/, album-art/, history CSV files, and backup/—then copy the music files separately.
On the destination computer, restore the data while TrackRate is closed, open the app, add the music folders at their new locations, and rescan unchanged audio. TrackRate’s audio identity can reconnect restored ratings, hashtags, lyrics, and playlists even when file paths changed, provided the audio bytes were not re-encoded or otherwise changed.
No questions match that search.