⚠️ AI-Generated Project Warning
This project was generated by AI in the spirit of "vibe coding" - an experimental approach to rapid development. While functional, the codebase may contain unconventional patterns, incomplete error handling, or areas that could benefit from refactoring.

ExtrarrFin is a Python tool that automates the download of special episodes (Season 0), behind-the-scenes extras, and musical themes for your Sonarr series and Radarr movies, using yt-dlp to search and download content from YouTube and other sources.

• 🔍 Automatic detection — retrieves all monitored series with monitored Season 0
• 📺 YouTube download — uses yt-dlp to download special episodes
• 🎯 Smart video matching — intelligent scoring system (see SCORING.md)
• 🏃 Dry-run mode — simulate without downloading
• ♻️ Duplicate detection — skips already-downloaded files (--force to override)
• 🔄 Sonarr/Radarr integration — triggers a scan after download
• 🎬 Radarr support — download extras for movies (tag mode)
• 🏷️ Tag mode — download behind-the-scenes via want-extras tag (see TAG_MODE.md)
• 🎵 Theme music — downloads theme.mp3 for every series and movie (ThemerrDB → TelevisionTunes → YouTube) ⚠️ work in progress — some titles may get incorrect matches (see below)
• 🔒 theme --no-fallback — curated sources only (ThemerrDB + TelevisionTunes), never a YouTube guess; unknown titles are reported failed instead
• 🔎 list-themes — dedicated command to check theme.mp3 status at a glance; --more-info adds Year & Network/Studio columns
• 📝 Subtitles — automatic download and SRT conversion
• 📺 STRM mode — streaming files instead of downloads (saves disk space)
• ⏰ Schedule mode — periodic automatic downloads
• 🐳 Docker support — Debian-based container image
• 📂 Directory mapping — remote execution with path remapping
• 🧹 Auto cleanup — removes incomplete .part files

# 1. Install
git clone https://github.com/yourusername/extrarrfin.git && cd extrarrfin
pip install -r requirements.txt

# 2. Configure
cp config.example.yaml config.yaml && nano config.yaml

# 3. Test
python extrarrfin.py test

# 4. Dry-run
python extrarrfin.py download --dry-run

# 5. Download
python extrarrfin.py download

The theme music mode (theme-mode) is still being fine-tuned. Known issues:

• ThemerrDB coverage — the curated database only holds a theme for roughly 60 % of series and 35 % of movies; the rest fall through to TelevisionTunes / YouTube. Series are matched by TMDB ID, so a title without a TMDB ID in Sonarr cannot use this source.
• Wrong match on YouTube — for short or generic titles (e.g. The Bear, The Penguin), the scorer may pick a video from an unrelated older show that shares a keyword.
• Orchestral/cover version — the YouTube fallback may prefer a cover or orchestral arrangement over the original theme.
• TelevisionTunes false positive — for titles with common words the slug-matching may land on a loosely related page.
• Permission errors — if the destination folder is owned by root (e.g. previous Docker run), the download will fail with Permission denied. Fix ownership before running.

Avoiding the uncertain matches: run python extrarrfin.py theme --no-fallback to use only the curated sources (ThemerrDB + TelevisionTunes). Titles no curated source knows are then reported as failed rather than filled with a scored YouTube guess.

Use --force to retry a title and --verbose to see the scoring details. Contributions and score tuning are welcome.

• Python 3.14+
• Sonarr instance with API key (required)
• Radarr instance with API key (optional, for movies)
• FFmpeg

→ Full installation guide

Use responsibly and in accordance with YouTube's Terms of Service and the copyright laws of your country.

Sonarr · Radarr · yt-dlp · Click · Rich

*Made with ❤️ for the arr community