#1 Feature: Playlist Import & Library Synchronization

Summary

Implement a playlist import system capable of importing playlists from multiple music platforms while preserving metadata and automatically organizing the local library.

The goal is to make MusicHub more than a downloader: it should become a complete personal music library manager capable of recreating playlists locally with high-quality metadata.

---

Motivation

Many users already have playlists on streaming platforms such as Spotify, YouTube Music or Deezer.

Instead of manually downloading tracks one by one, MusicHub should be able to:

• Import an existing playlist.
• Retrieve all available metadata.
• Download the corresponding audio.
• Embed metadata and artwork.
• Organize the files in the local library.
• Keep the playlist synchronized over time.

---

Supported Platforms

Initial targets

• YouTube
• YouTube Music
• Spotify
• Deezer
• SoundCloud

Future support

• Apple Music
• TIDAL
• Bandcamp
• Public playlist URLs
• Local .m3u / .m3u8 playlists

---

Proposed Workflow

Import Playlist
        ↓
Read playlist information
        ↓
Retrieve track list
        ↓
Match tracks
        ↓
Download audio
        ↓
Fetch metadata
        ↓
Download artwork
        ↓
Embed metadata
        ↓
Organize library
        ↓
Create local playlist

---

Metadata Preservation

Whenever available, preserve:

• Track title
• Artist(s)
• Album
• Album artist
• Track number
• Disc number
• Release year
• Genre
• Cover artwork
• Duration
• ISRC
• Explicit flag

Future:

• Lyrics
• Composer
• BPM
• Musical key

---

Metadata Providers

Possible providers:

• MusicBrainz
• Cover Art Archive
• Deezer API
• Spotify API
• Last.fm (future)

---

Synchronization

Support optional playlist synchronization.

Features:

• Detect newly added tracks.
• Download only missing songs.
• Skip duplicates.
• Remove deleted tracks (optional).
• Manual sync.
• Scheduled automatic sync.

---

Duplicate Detection

Avoid downloading the same song multiple times.

Possible matching strategies:

• ISRC
• Artist + Title
• Artist + Album + Track Number
• Audio fingerprint (future)

---

User Experience

The import wizard should allow users to:

• Paste a playlist URL.
• Choose the destination folder.
• Select the preferred audio format.
• Configure audio quality.
• Choose metadata providers.
• Decide whether artwork should be downloaded.
• Enable automatic synchronization.

Display:

• Total tracks.
• Successfully imported.
• Failed.
• Skipped.
• Duplicates found.
• Overall progress.

---

Possible Future Enhancements

• Smart search when a track cannot be found.
• Automatic metadata correction.
• Multi-source fallback.
• Playlist export.
• Import from CSV.
• Import from JSON.
• Bulk playlist imports.
• Cross-platform playlist migration.

---

Benefits

• Makes MusicHub a complete personal music library manager rather than just a download interface.
• Greatly improves migration from streaming services.
• Keeps local libraries organized and synchronized.
• Preserves as much metadata as possible.
• Provides a seamless experience for self-hosted music collections.

---

Acceptance Criteria

• Import playlists from supported platforms.
• Create a local playlist automatically.
• Preserve track order.
• Download and embed metadata.
• Download album artwork.
• Organize files according to library rules.
• Detect duplicate tracks.
• Support optional playlist synchronization.
• Show detailed progress and import statistics.
• Expose the feature through both the Web UI and REST API.