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**
```bash
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

```yaml
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

```bash
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:

```bash
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

```bash
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](https://github.com/yt-dlp/yt-dlp)