-
Notifications
You must be signed in to change notification settings - Fork 1
Restoring backups across operating systems
Alternative Play Count, Ratings Light and Migration Assistant share the same backup and restore logic. This page explains how restoring a backup created on one operating system (macOS, Linux/Daphile, or Windows) onto a different one is handled, and why a small number of tracks can occasionally remain unmatched after such a restore.
Restoring within the same operating system always works exactly as before. When the source and target operating systems differ, the plugin automatically compensates for two platform-level differences that would otherwise prevent tracks from being found:
-
Unicode normalization. macOS decomposes accented characters (e.g. "não" is stored as
n+a+ a separate accent mark), while Linux and Windows normally compose them into a single character. The plugin tries both forms when matching a track, so this is invisible to you. - Windows character encoding. Windows itself stores non-ASCII filenames using the system's active ANSI codepage rather than UTF-8. Backups created on Windows record which codepage was used, and the plugin uses that information to decode filenames correctly when restoring elsewhere (and vice versa).
Because of this, restoring a backup from any of the three supported operating systems onto any other should match every track whose filename doesn't run into one of the two limitations below.
Two situations aren't specific to this plugin - they come from real differences between filesystems and can't be reliably resolved automatically:
1. Characters that are valid on one filesystem but forbidden on another.
Windows/NTFS forbids several characters that macOS and Linux allow without restriction: < > : " | ? *, as well as filenames ending in a space or a period. A file using one of these characters simply cannot exist under its original name on a Windows system - whatever tool was used to copy the files there had to rename it somehow, and there's no reliable way to know how. This only affects restores where the target is Windows; restoring a Windows-created backup onto macOS or Linux isn't affected by this at all, since those filesystems are far less restrictive.
2. A macOS-specific display quirk involving /.
On macOS, Finder displays a / character in filenames that actually contain a : on disk (a historical carryover from the classic Mac OS, which used : as its path separator). A track named with a / as a stylistic separator (e.g. an artist or track title like "A / B") can end up recorded with a literal / in the backup - which is structurally ambiguous, since / is also the path separator itself. Whatever tool copied the files to a non-macOS system had to resolve that ambiguity somehow (turning it into an extra folder, replacing it with another character, etc.), and again there's no reliable way to predict the result. This only affects tracks that originated on macOS, regardless of the restore's target system.
In both cases, the track itself is still fully present on the target system - just under a different, unpredictable filename that can't be derived from the backup automatically.
If any tracks were skipped during a restore, the server log names how many and why. A full list of the affected tracks is also written to a text file in the plugin's own folder (e.g. APC_Restore-Unmatched-Tracks.txt or RL_Restore-Unmatched-Tracks.txt), so you can review exactly which tracks were affected.
AlternativePlayCount's play history backup is restored separately from the main track statistics, and without the same file-matching logic described above - each entry is written back using the path exactly as recorded in the backup. When restoring across operating systems, local file entries are therefore skipped automatically, since their paths can't be resolved on a different system; the server log reports how many were skipped. Remote entries that are part of your LMS library aren't file paths in this sense and are always restored normally, regardless of the operating system.