YouTube Playlist Sync

A cross-platform tool for downloading and keeping in sync a local copy of entire YouTube playlists as MP3 or MP4 files, using yt-dlp & ffmpeg.

Supports audio, video, or both download modes, music and videos are numbered as they are on your youtube playlist, playlist cleanup, and configurable parallel download options. Local-first YouTube playlist synchronization client.

What’s Included

• Scanner (yt-dlp extract-only), diff engine, filesystem scan
• Safe reordering via two-pass rename, recycle deletions
• Async download queue with simple retry (yt-dlp Python API)
• SQLite metadata; DB updates on rename/download/delete; last_sync
• Optional event publishing for future GUI/logs

Requirements

• Python 3.10+
• yt-dlp (pip)
• ffmpeg (for audio extraction)

Configure

Create/edit config/yt-playlist-config.json:

{
  "playlists": [
    {
      "url": "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID",
      "download_mode": "audio",
      "save_path": "./downloads"
    }
  ],
  "yt_dlp_path": "yt-dlp",
  "ffmpeg_path": "ffmpeg"
}

Run

• Compute-only:

python -m src.app.cli

• Apply actions:

python -m src.app.cli --apply

• Single playlist (0-based index):

python -m src.app.cli --apply --playlist 0

Data & Layout

• Database: app/data/app.db
• Outputs: <save_path>/audio and/or <save_path>/video
• Recycle bin: <save_path>/.recycle/{audio,video}

Roadmap (short)

• Scheduler (periodic sync), richer retries/logging
• GUI (PySide6) wired to EventBus
• Enhanced config validation