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

GUI (PySide6 Essentials) playlist manager + sync runner
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 (last_sync, download state)

Requirements

If you download a -ffmpeg release: no extra dependencies
If you download a non-ffmpeg release: install ffmpeg and ensure it's on PATH (needed for audio and both modes)

Download

Download the latest release from this repo's Releases page and pick one:

ytpl-sync-windows-{version}-ffmpeg.zip / ytpl-sync-linux-{version}-ffmpeg.tar.gz (ffmpeg bundled)
ytpl-sync-windows-{version}.zip / ytpl-sync-linux-{version}.tar.gz (no ffmpeg bundled)

Configure

Application uses a json config that canbe edited from UI or manually

{
  "ffmpeg_path": "./bin/ffmpeg.exe",
  "max_parallel_downloads": 2,
  "retry_max_retries": 2,
  "retry_delay_seconds": 1.5,
  "playlists": [
    {
      "url": "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID",
      "download_mode": "video",
      "max_download_quality": "1080p",
      "save_path": "./downloads",
      "name": "my favorite playlist"
    }
  ]
}

max_download_quality:

Limits yt-dlp download quality (e.g. "2160p", "1440p", "1080p", "720p", "360p"). This only affects the downloaded video format selection.
Use "best" for no height cap (highest available).
If the requested max quality isn't available for a video, the best available quality is chosen.

download_mode:

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

Queue / retry:

max_parallel_downloads: number of concurrent download workers.
retry_max_retries: how many times a failed download job is retried.
retry_delay_seconds: base delay before retry; increases with backoff.

Run

Run ytpl-sync.exe (GUI).

Tray

The app supports minimizing to tray on close if the OS provides a system tray; use the tray icon menu to quit.
Tray behavior settings (Settings page):
- close_to_tray: close hides to tray (keeps running).
- minimize_to_tray: minimize hides to tray.
- start_minimized_to_tray: start hidden in tray.

Data & Layout

Database: db/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
Enhanced config validation
UX polish (settings, progress, error messages)

3.5 KiB Raw Permalink Blame History