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+
• ffmpeg (needed for audio and both modes)

Quick start:

Download the latest release from releases page

Configure

On first run, the app will auto-create a default yt-playlist-config.json in the project root (if missing).

Create/edit yt-playlist-config.json:

{
  "config_path": "./",
  "ffmpeg_path": "./bin/ffmpeg.exe",
  "playlists": [
    {
      "url": "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID",
      "download_mode": "audio",
      "save_path": "./downloads"
    }
  ]
}

config_path (optional):

• If set to a string path, the app loads the config from that file instead (path is relative to the current config file).

download_mode:

• video: download playlist videos as muxed .mp4 (no ffmpeg processing)
• audio: download muxed .mp4, extract .mp3, delete the .mp4
• both: download muxed .mp4, extract .mp3, keep both files

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