Feature: merge songs by isrc

[TheTastyHanuta]

Summary

This PR adds ISRC-based track deduplication so the same recording is counted as one track even when Spotify exposes it through multiple track IDs, such as on singles, EPs, albums, deluxe editions, or regional releases.

Previously each Spotify track ID was treated as a separate song. This could split listening stats for the same recording across multiple track entries.

This fixes #465 and #469.

What Changed

Track documents can now store Spotify ISRC metadata. When new Spotify tracks are processed, the server uses the ISRC to resolve them to an existing canonical track where possible instead of creating duplicate track records.

Listening history now keeps track identity and release context separate:

• Infos.id points to the canonical track/recording.
• Infos.albumId keeps the album or release that was actually listened to.

This means track stats can count the same recording together, while album stats still count toward the release the user actually played.

For example, if the same song appears on both an EP and an album:

• the song’s track count is shared,
• an EP listen still counts toward the EP,
• an album listen still counts toward the album.

The normal Spotify sync flow and both Spotify privacy importers were updated to use this same behavior.

Existing Data Migration

A manual migration script was added for users who want to deduplicate their existing listening history.

The migration is dry-run by default and can generate a report of the planned or applied merges. Full usage instructions are documented in:

apps/server/ISRC_DEDUPLICATION.md

If users do not run the migration, the application continues to work, but existing duplicate tracks remain split until migrated.

Additional Fixes

Album and artist album statistics were adjusted to use the listened release from the history entry instead of the canonical track’s album. This avoids empty or incomplete album pages after deduplication and keeps album rankings accurate.

Testing

No testing of the privacy or full privacy import was done.
Manually tested with duplicate Spotify tracks sharing the same ISRC, including recordings that appear on multiple releases. I have been running this version along side my old instance and so far no problems or inconsistencies occurred.

Before

Same track listens from different albums are counted separate.

After

Entries have been merged but album listens stay the same.

Note

I don't know if this ever gets merged, but I will continue using both versions in parallel and compare both at the end of the year. I am open for suggestions: maybe something like a toggle switch in the settings could be implemented, etc.