youtube-sync-docker/README.md

YouTube Channel Sync Docker

Automatically download and organize YouTube channel videos for Emby, Plex, or Jellyfin media servers.

Features

• Downloads videos in best quality up to 1080p (configurable)
• Organizes videos by season folders (year-based)
• Proper episode naming for media servers: S2026E001 - Video Title - [VideoID].mp4
• Embeds thumbnails and metadata
• Creates tvshow.nfo files for Emby/Plex
• Tracks downloaded videos to avoid re-downloading
• Supports YouTube cookies for authentication (bypasses bot detection)
• Scheduled automatic syncs via cron
• Lightweight Alpine Linux base (~200MB)

Quick Start (Unraid)

1. Install from Community Applications: Search for "YouTube Sync"
2. Configure paths:
   • Download Directory: /mnt/user/media/YouTube (or your media location)
   • Config Directory: /mnt/user/appdata/youtube-sync
3. Edit /mnt/user/appdata/youtube-sync/channels.txt and add your channels
4. (Optional) Add YouTube cookies to /mnt/user/appdata/youtube-sync/cookies.txt
5. Start the container

Configuration

channels.txt Format

# Format: CHANNEL_ID|Channel Name
UCfDNi1aEljAQ17mUrfUjkvg|Alton Brown
UCoq2qlWgvvKJzW_hBkLIE8w|Flavour Trip

Finding Channel IDs:

1. Go to the channel's main page on YouTube
2. View page source (Ctrl+U or Cmd+U)
3. Search for "channelId" or check the URL structure

YouTube Cookies (Optional but Recommended)

YouTube may block downloads without authentication. To fix this:

Method 1: Browser Extension

1. Install "Get cookies.txt LOCALLY" extension for Firefox/Chrome
2. Go to YouTube.com while logged in
3. Click the extension icon and export cookies
4. Save as /mnt/user/appdata/youtube-sync/cookies.txt

Method 2: yt-dlp command

yt-dlp --cookies-from-browser firefox --cookies cookies.txt --skip-download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Environment Variables

Variable	Default	Description
SYNC_SCHEDULE	0 2 * * *	Cron schedule (2 AM daily). Use manual to disable.
MAX_QUALITY	1080	Maximum video quality (480, 720, 1080, 1440, 2160)
SLEEP_INTERVAL	2	Seconds between downloads (helps avoid rate limiting)
TZ	America/Phoenix	Timezone for scheduling
PUID	99	User ID for file ownership
PGID	100	Group ID for file ownership

Docker Compose

version: '3'
services:
  youtube-sync:
    image: azcomputerguru/youtube-sync:latest
    container_name: youtube-sync
    environment:
      - SYNC_SCHEDULE=0 2 * * *
      - MAX_QUALITY=1080
      - SLEEP_INTERVAL=2
      - TZ=America/Phoenix
      - PUID=99
      - PGID=100
    volumes:
      - /mnt/user/media/YouTube:/downloads
      - /mnt/user/appdata/youtube-sync:/config
    restart: unless-stopped

Docker CLI

docker run -d \
  --name youtube-sync \
  -e SYNC_SCHEDULE="0 2 * * *" \
  -e MAX_QUALITY=1080 \
  -e TZ=America/Phoenix \
  -v /mnt/user/media/YouTube:/downloads \
  -v /mnt/user/appdata/youtube-sync:/config \
  azcomputerguru/youtube-sync:latest

Manual Sync

To run a sync immediately:

docker exec youtube-sync /app/sync.sh

Output Structure

/downloads/
├── Alton Brown/
│   ├── tvshow.nfo
│   ├── .downloaded.txt (tracking file)
│   ├── Season 2024/
│   │   ├── S2024E001 - Title - [VideoID].mp4
│   │   ├── S2024E001 - Title - [VideoID].info.json
│   │   └── ...
│   └── Season 2025/
│       └── ...
└── Flavour Trip/
    ├── tvshow.nfo
    └── Season 2026/
        └── ...

Emby/Plex Setup

1. Add the download directory as a TV Shows library
2. Use "Local Media Assets (TV)" scanner
3. Episodes will appear organized by channel name and year

Troubleshooting

"Sign in to confirm you're not a bot" Error

YouTube is blocking downloads. Solution: Add cookies.txt (see Configuration section)

Videos Not Downloading

1. Check channels.txt format (must be CHANNEL_ID|Name, no spaces around |)
2. Verify channel IDs are correct
3. Check container logs: docker logs youtube-sync
4. Ensure /downloads directory is writable

Scheduling Not Working

1. Verify cron schedule format is correct
2. Check timezone is set properly
3. Set SYNC_SCHEDULE=manual and run manually to test
4. Check logs: docker logs youtube-sync

Building From Source

git clone https://github.com/azcomputerguru/youtube-sync-docker
cd youtube-sync-docker
docker build -t youtube-sync .

Support

Issues and pull requests: https://github.com/azcomputerguru/youtube-sync-docker

License

MIT License - See LICENSE file for details

Credits

Built by Arizona Computer Guru LLC using yt-dlp