Abgleich der Playlist-Synchronisierung (PSM)

Hast du dich schon einmal gefragt, welche Tracks in deinen Streaming-Playlists du bereits besitzt, welche fehlen und wie du funktionierende lokale Playlists erstellen kannst, ohne sie manuell neu aufzubauen? playlist-sync-matcher (PSM) ist ein kleines persönliches Projekt, das die Lücke zwischen Streaming-Playlists (derzeit Spotify) und deiner lokalen Musiksammlung schließt. Es erzeugt M3U/M3U8-Playlists, die auf echte Dateien verweisen, und hebt fehlende Inhalte hervor – das spart Zeit und Aufwand.

Was es tut (und was nicht)

PSM automatisiert die Zuordnung deiner Streaming-Playlists zu den Musikdateien, die du bereits lokal hast:

• Verlinkt deine lokalen Dateien – Jeder Playlisteintrag verweist auf die echte MP3/FLAC-Datei auf deinem Laufwerk.
• Zeigt, was fehlt – Klare Reports zu Tracks und Alben, die lokal nicht vorhanden sind.
• Erstellt standardkonforme M3U-Playlists – Kompatibel mit jedem Musikplayer.

Wichtig: PSM lädt keine Audiodateien herunter, kopiert sie nicht und synchronisiert sie nicht. Es erstellt lediglich Playlists, die auf bereits vorhandene Dateien auf deiner Festplatte verweisen, und markiert Lücken. Wenn ein Track fehlt, erscheint er in den Reports, damit du ihn selbst beschaffen kannst.

Dieses Tool richtet sich an Musiksammler, die ihre Sammlung an ihren Streaming-Gewohnheiten ausrichten und ihre vorhandenen lokalen Dateien in Standard-Playern nutzen möchten.

Kernfunktionen

• Spotify-Integration: Playlists + "Liked Tracks" via OAuth.
• Schnelles Bibliothek-Scanning: Mtime+size-basierter Fast-Scan-Modus überspringt unveränderte Dateien.
• Intelligentes Matching: Geschichtete Scoring-Engine mit Vertrauensstufen (CERTAIN/HIGH/MEDIUM/LOW). Mehrere Signale: exakter/unscharfer Text, Albumkontext, Jahr, Dauer, ISRC.
• Early-Exit-Optimierung bei hochsicheren Matches.
• Flexibler Export: Drei Modi (strict | mirrored | placeholders) mit kollisionssicheren Dateinamen.
• Optionale Organisation: Playlists nach Besitzer in Ordnern gruppieren.
• Optionale GUI: Eine einfache Desktop-App, die dieselbe Engine mit grafischer Oberfläche ausführt (siehe unten).
• Schlanker Watch-Modus: Überwacht kontinuierlich deine Bibliothek und Datenbank auf Änderungen und wendet inkrementelle Updates an. Vermeidet vollständige Rebuilds; reagiert in der Regel in Sekunden mit kleinem Debounce.
• Umfangreiche interaktive Reports: Umfassende HTML- + CSV-Reports mit Sortierung, Suche, Pagination. Gematchte Tracks mit Konfidenzwerten und Match-Strategien.
• Nicht gematchte Tracks/Alben nach Popularität sortiert für klügere Beschaffungsentscheidungen.
• Playlist-Abdeckungsanalyse mit Drilldown-Details.
• Bibliotheksqualitätsanalyse (fehlende Metadaten, Erkennung niedriger Bitraten).
• Klickbare Spotify-Links in allen Reports.
• Responsives Dashboard ( index.html ) für einfache Navigation.
• Match-Diagnostik: Konsolenausgabe + detaillierte Reports zur Untersuchung von Randfällen.
• Qualitätsanalyse: Identifiziert Metadatenlücken und Dateien mit niedriger Bitrate, nach Album gruppiert für effizientes Beheben.
• Provider-Ready-Architektur: Composite-(id, provider)-Schema + Registry für zukünftigen Multi-Service-Support.

Typischer Workflow

psm login      # OAuth authentication (first time)
psm pull       # Fetch Spotify playlists and tracks
psm scan       # Index local music files
psm match      # Match streaming tracks to local files (auto-generates reports)
psm export     # Generate M3U playlists
psm analyze    # Analyze library quality (auto-generates quality reports)

Oder führe die komplette Datensynchronisations-Pipeline mit einem Befehl aus:

psm build      # Runs full pipeline: pull → scan → match → export

Hinweis: build führt die Datensynchronisations-Pipeline aus, nicht die Software-Kompilierung.

Für fortlaufende Aktualisierungen, während du deine Bibliothek änderst oder neue Daten abrufst:

psm build --watch   # Lean watch mode with incremental updates

Ergebnisse erkunden:

# Open the interactive report dashboard
start data/export/reports/index.html  # Windows
open data/export/reports/index.html   # Mac/Linux

Einzelne Reports enthalten:

• Matched Tracks – Alle erfolgreichen Matches mit Konfidenzwerten, Strategien und Metadatenvergleich.
• Unmatched Tracks – Fehlende Tracks nach Playlist-Popularität sortiert, mit Spotify-Links für einfache Beschaffung.
• Unmatched Albums – Lücken nach Album gruppiert, um strategische Downloads zu unterstützen.
• Playlist Coverage – Fertigstellungsprozentsatz pro Playlist mit Drilldown bis auf Track-Ebene.
• Metadata Quality – Dateien mit fehlenden Tags oder niedriger Bitrate, nach Album gruppiert für stapelweises Beheben.

Alle Reports sind sortier- und durchsuchbar und enthalten klickbare Spotify-Links, bereitgestellt durch jQuery DataTables.

GUI (optional)

Es gibt auch eine kleine Desktop-App, falls du einen visuellen Workflow bevorzugst. Sie nutzt dieselbe zugrunde liegende CLI und Konfiguration.

Was sie bietet:

• Master-Detail-Ansicht: Playlists links, Tracks rechts
• Toolbar-Aktionen: Build, Pull, Scan, Match, Export, Report, Open Reports, Refresh, Watch Mode
• Schnellfilter: Playlist, Artist, Album, Year, Matched, Confidence, Quality, plus Suche
• Live-Log-Panel und eine Statusleiste mit Summen (Tracks, Matched %, Playlists) Die GUI ist optional; die CLI bleibt die primäre Schnittstelle.

Technische Hinweise

• Implementiert in Python (3.10+) mit Standalone-Executables via PyInstaller gebaut (CI baut derzeit mit Python 3.12).
• GUI gebaut mit PySide6 (Qt for Python); nutzt CLI-Subprozesse für Aktionen und streamt Logs/Status ins UI.
• SQLite-Datenbank mit Indizes auf normalisiertem Text und ISRC-Feldern für schnelle Lookups.
• Service-Layer hält die CLI schlank (Separation of Concerns).
• Umgebungs-/ .env-basierte Konfiguration ( PSM__SECTION__KEY pattern).
• Caching + Batching für Performance (Normalization-Cache, batched Commits).
• Sicherer Single-Process-DB-Zugriff (einfaches Locking).

Warum es existiert

PSM wurde entwickelt, um das Synchronisieren von Streaming-Playlists mit lokalen Bibliotheken zu vereinfachen. Statt Tracks manuell zu suchen oder Playlists neu aufzubauen, automatisiert PSM den Prozess – ordnet Streaming-Tracks lokalen Dateien zu, hebt Lücken hervor und exportiert einsatzfertige Playlists. Das spart Zeit, reduziert Frust und hilft dir, das Beste aus deinen Streaming-Abos und deiner eigenen Musiksammlung herauszuholen.

Mitmachen

Ich hoffe, dieses Projekt ist auch für andere nützlich! Wenn du Unterstützung für weitere Streaming-Anbieter sehen möchtest oder Ideen für Verbesserungen hast, sind Beiträge willkommen. Schau dir das Repository auf GitHub an: https://github.com/vtietz/playlist-sync-matcher.