Siphon

A self-hosted playlist downloader & watcher that automatically downloads new additions on a schedule. Built to address shortcomings found in tools like MeTube.

Siphon uses YT-DLP and runs as a daemon with a web UI. Register your playlists, set a schedule, and forget about it. New tracks show up in your library automatically. Any platform supported by yt-dlp works, though Siphon is built and tested with a focus on YouTube.

Siphon is primarily developed using spec-driven development through OpenSpec. Every feature starts as a specification before a single line of code is written. This is not vibe coding. There are actual specs, actual designs, and actual task lists. Revolutionary, right?

Features

• Download - Entire playlists or single videos, with configurable concurrent workers.
• Format selection - Download audio (MP3, OPUS) or video formats (MP4, MKV, WEBM) with quality options.
• Playlist sync - Monitors playlists and auto-downloads newly added videos.
• Scheduled syncing - Configurable per-playlist sync intervals (hourly, daily, whatever you want).
• Smart auto-renaming - Cleans up filenames and titles using embedded metadata and MusicBrainz lookups.
• Manual renaming - Manually rename individual downloaded items from the Web UI or CLI. Changes are applied on disk and in metadata.
• SponsorBlock integration - Automatically removes sponsor segments, intros, outros and non-music sections from downloads using the SponsorBlock community database.
• Cookie support - Upload a browser cookie file to unlock private playlists, age-restricted videos, and members-only content.
• Audio metadata embedding - Embeds artist, title, album and cover art into audio files.
• Web UI - Manage playlists, view download history, configure settings and monitor progress from your browser.
• CLI - Full command-line interface for automation, scripting and debugging.
• Container-first - Designed to run in Docker, built for Unraid.

Screenshots

Setup

Unraid

Siphon is built container-first, designed for Unraid.
Install it from Community Apps (Coming soon):

1. Open the Community Apps plugin in your Unraid dashboard.
2. Search for Siphon.
3. Click Install and configure:
   • Downloads path - where your media gets saved (e.g. /mnt/user/downloads/siphon/)
   • App Data path - where the database and logs live (e.g. /mnt/user/appdata/siphon/)
   • PUID/PGID - user/group IDs for file ownership (defaults: 99/100)
4. Start the container and open the web UI on port 8778.

Docker

docker run -d \
  --name siphon \
  -p 8778:8000 \
  -v /path/to/downloads:/app/downloads \
  -v /path/to/appdata:/app/.data \
  -e PUID=1000 \
  -e PGID=1000 \
  ghcr.io/whydahgally/siphon:latest

Or with docker-compose:

services:
  siphon:
    image: ghcr.io/whydahgally/siphon:latest
    container_name: siphon
    restart: unless-stopped
    ports:
      - "8778:8000"
    volumes:
      - /path/to/downloads:/app/downloads
      - /path/to/appdata:/app/.data
    environment:
      - PUID=1000
      - PGID=1000

The web UI is available at http://<your-ip>:8778.

CLI Commands

Browser Cookies

Some content requires authentication to download (private playlists, age-restricted videos, members-only posts). See the yt-dlp cookie authentication guide.

Note: Using extracted browser cookies may result in account bans.

Configuring cookies

• Web UI - Go to Settings → Cookies and click the upload button.
• CLI - siphon config cookie-file /path/to/cookies.txt

Cookie File Security

Siphon communicates over HTTP (no TLS). If you are accessing Siphon over Wi-Fi from a remote server, a compromised device on the same network could intercept it.

Safe one-time alternative: copy the file directly into the container filesystem without touching the network:

docker exec -i siphon sh -c 'cat > /app/.data/cookies.txt' < /path/to/cookies.txt

Note: If you copy the cookie file manually while Siphon is running, the backend will detect it on the next download or sync. However, the web UI will only reflect the change after a browser refresh.

For ongoing encrypted access, place a TLS-terminating reverse proxy in front of Siphon.

Contributing

Contributions are welcome! AI-generated code is also welcome, but only if it follows spec-driven development through OpenSpec. No yolo PRs. Every change needs specs committed alongside the code.

Before opening a PR:

• New features - open a Discussion first to align on scope and approach before writing any specs or code.
• Bug fixes - open an Issue first to confirm the bug and agree on the fix.

When raising a PR:

• Include the OpenSpec artifacts (proposal, design, specs, tasks) in the openspec/changes/ directory.
• Ensure specs exist for any new capabilities under openspec/specs/.
• Test your changes locally following the steps provided in the Local Development section below.

Local Development

Prerequisites: Python 3.10+, Node.js 22+, ffmpeg

# Clone and set up
git clone https://github.com/WhydahGally/Siphon.git
cd Siphon

# Python environment
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Start the daemon
siphon start

# In another terminal, run CLI commands
siphon list

For the web UI:

cd src/ui
npm install
npm run dev

Running Tests

Unit tests (no daemon required):

pytest tests/unit/ -v

End-to-end tests require a running network connection and real URLs. Create tests/.env with your secrets:

export E2E_PLAYLIST_URL="https://www.youtube.com/playlist?list=..."
export E2E_SINGLE_VIDEO_URL="https://www.youtube.com/watch?v=..."
export E2E_MB_USER_AGENT="YourApp/1.0 (you@example.com)"
# macOS only - fixes SSL verification for MusicBrainz lookups
export REQUESTS_CA_BUNDLE=/opt/homebrew/etc/openssl@3/cert.pem

Then run (do not have the dev daemon running - the suite manages its own):

make -f tests/Makefile e2e

Submitting Issues

Siphon is a wrapper around yt-dlp. Many issues - especially download failures, authentication errors, format extraction problems are caused by yt-dlp, not Siphon.

Common yt-dlp issues:

• "Video unavailable" - the video is private, deleted, or region-locked.
• "Sign in to confirm your age" - requires cookie authentication. See the Browser Cookies section to configure a cookie file.
• Format extraction errors - usually fixed by updating yt-dlp. Siphon pins a specific yt-dlp version; check if a newer version resolves it.

Before opening an issue, check if it's a yt-dlp problem:

• Ensure that you are using the latest available version of Siphon. Siphon pins yt-dlp to a specific version and updates it with each release.
• Try downloading the same URL directly with yt-dlp from inside the Siphon container: docker exec siphon yt-dlp <url>.
• If yt-dlp fails, the issue is upstream. Check the yt-dlp version Siphon is using (shown in the web UI settings page) and search for matching issues in yt-dlp issues.
• If yt-dlp works fine with the same version or if there is no Siphon update available, we want to hear about it.

When opening an issue, include the following:

1. A description of the problem and what you expected to happen.
2. The playlist or video URL that triggered the issue.
3. Your Siphon configuration at the time the issue occurred (auto-rename, sync interval, sb etc.).
4. Your Siphon version and yt-dlp version (shown in the web UI settings page or use the CLI).
5. The relevant section of your log file (set log level to DEBUG first to capture more detail).
6. Steps to reproduce the issue.

Logging

Siphon writes a rolling log file to .data/siphon.log (5 MB max, 1 backup). In Docker, this is inside the app data volume you mapped (e.g. /path/to/appdata/siphon.log). Set the log level to DEBUG before reproducing an issue to capture the most detail.

Log Levels

Siphon supports four log levels, configurable via the CLI or the Settings page in the web UI:

Set the log level:

siphon config log-level DEBUG

Browser Logs

Siphon can stream server logs to the browser console for real-time debugging. Enable this in the web UI settings page by toggling Browser Logs. Once enabled, open the browser developer tools (F12) to see log output in the console.

License

MIT