Episeerr

Smart episode management for Sonarr - Get episodes as you watch, clean up automatically when storage gets low. This project started as scratching my own itch - I wanted more granular series management and couldn't find exactly what I wanted. I'm not a programmer by trade, but I had a clear vision for the solution I needed. I used AI as a development tool to help implement my ideas faster, just like any other tool. The creativity, problem-solving, architecture decisions, and feature design are all mine - AI helped with code, syntax and implementation details. Although I run everything in my own production environment first, it is catered to my environment and is use at your own risk. All code is open source for anyone to review and audit. The tool has been useful for me, and I shared it in case others can benefit from it too - but I absolutely understand if some prefer to stick with established solutions.

[🔓 Sponsor to keep the gate OPEN!] I use Claude to support development and fixes and only update subscription when I can.

📋 Table of Contents

What It Does
Quick Start
Installation
Plex Watchlist Sync
- Setup
- Getting Your Plex Token
Webhook Setup
How to Use
Features Explained
Configuration Examples
Troubleshooting
Screenshots
FAQ
Support

What It Does

Episeerr gives you four independent features for TV episode management:

Feature	What It Does	Use Case
🎯 Episode Selection	Choose specific episodes to download	Try pilots, skip seasons, selective downloads
⚡ Viewing Automation	Next episode ready when you watch	Binge watching, always-ready episodes
💾 Storage Management	Automatic cleanup based on time/viewing	Limited storage, inactive show cleanup
🔄 Plex Watchlist Sync	Add to Plex watchlist, Episeerr handles the rest	Zero-effort adding, full selection control
📌 Always Have	Baseline episodes always present and protected	Showcase libraries, permanent pilots, season placeholders

Use one, some, or all - they work independently!

Quick Start

Get running in 5 minutes:

# 1. Create docker-compose.yml (minimal setup)
services:
  episeerr:
    image: vansmak/episeerr:latest
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - ./data:/app/data
    ports:
      - "5002:5002"
    restart: unless-stopped

# 2. Start container
docker-compose up -d

# 3. Open http://your-server:5002/setup
# 4. Configure Sonarr, TMDB, and optional services
# 5. Create a rule, add a series, start watching!

Restart container for changes to take effect That's it! No .env file needed - configure everything via the GUI.

For automation: Set up webhooks ⬇️

Installation

Two Ways to Configure:

GUI Setup (Recommended) - Use /setup page, no .env file needed
Environment Variables - Traditional .env file (still supported)

Docker Compose (Recommended)

Create docker-compose.yml:

services:
  episeerr:
    image: vansmak/episeerr:latest
    container_name: episeerr
    environment:
      # ============================================
      # REQUIRED
      # ============================================
      - SONARR_URL=http://your-sonarr:8989
      - SONARR_API_KEY=your_sonarr_api_key
      - TMDB_API_KEY=your_tmdb_read_access_token
      
      # ============================================
      # OPTIONAL - For Viewing Automation (pick ONE media server)
      # ============================================

      # Option A: Plex (recommended — native webhooks, no Tautulli needed)
      #   Requires Plex Pass for webhook support.
      #   Configure webhook in Plex: Settings → Webhooks
      #   URL: http://<episeerr>:5002/api/integration/plex/webhook
      #   Detection mode + token configured via /setup page (GUI recommended)
      #
      # - PLEX_URL=http://your-plex:32400
      # - PLEX_TOKEN=your_plex_token

      # Option A2: Tautulli (Plex without Plex Pass, or for richer watch history)
      #   ⚠️  Do NOT use alongside Plex native webhooks — configure one or the other.
      #   Webhook URL: http://<episeerr>:5002/api/integration/tautulli/webhook
      #   Legacy URL:  http://<episeerr>:5002/webhook  (still supported)
      #
      # - TAUTULLI_URL=http://your-tautulli:8181
      # - TAUTULLI_API_KEY=your_tautulli_key

      # Option B: Jellyfin (choose mode A or B in /setup, not via env vars)
      #   Webhook URL: http://<episeerr>:5002/api/integration/jellyfin/webhook
      #   Notification type: PlaybackProgress (real-time) or Session Start (polling)
      #
      # - JELLYFIN_URL=http://your-jellyfin:8096
      # - JELLYFIN_API_KEY=your_jellyfin_api_key
      # - JELLYFIN_USER_ID=your_username
      # - JELLYFIN_TRIGGER_PERCENTAGE=50.0   # polling mode
      # - JELLYFIN_POLL_INTERVAL=900          # polling mode
      # - JELLYFIN_TRIGGER_MIN=50.0           # real-time mode
      # - JELLYFIN_TRIGGER_MAX=55.0           # real-time mode

      # Option C: Emby
      #   Webhook URL: http://<episeerr>:5002/api/integration/emby/webhook
      #   Events: playback.start, playback.stop
      #
      # - EMBY_URL=http://your-emby:8096
      # - EMBY_API_KEY=your_emby_api_key
      # - EMBY_USER_ID=your_username
      # - EMBY_TRIGGER_PERCENTAGE=50.0
      # - EMBY_POLL_INTERVAL=900
      
      # ============================================
      # OPTIONAL - For Request Integration
      # ============================================
      - JELLYSEERR_URL=http://your-jellyseerr:5055
      - JELLYSEERR_API_KEY=your_jellyseerr_key
      # OR
      - OVERSEERR_URL=http://your-overseerr:5055
      - OVERSEERR_API_KEY=your_overseerr_key
      
      # ============================================
      # OPTIONAL - Authentication (Security)
      # ============================================
      # Uncomment to enable password protection:
      # - REQUIRE_AUTH=true
      # - AUTH_USERNAME=admin
      # - AUTH_PASSWORD=your-password-here
      # - SECRET_KEY=generate-random-key  # Optional: auto-generated if not set
      
      # ============================================
      # OPTIONAL - Quick Links in Sidebar
      # ============================================
      - CUSTOMAPP_URL=http://192.168.1.100:8080
      - CUSTOMAPP_NAME=My Custom App
      - CUSTOMAPP_ICON=fas fa-cog

    volumes:
      - ./config:/app/config     # Configuration files
      - ./logs:/app/logs         # Log files
      - ./data:/app/data         # Database and temp data
      - ./temp:/app/temp         # Temporary processing
    ports:
      - "5002:5002"
    restart: unless-stopped

Start:

docker-compose up -d

Access:

http://your-server:5002

Unraid Untested by me

1. Add Custom Template

Create /boot/config/plugins/community.applications/private/episeerr/my-episeerr.xml:

<?xml version="1.0"?>
<Container version="2">
  <Name>episeerr</Name>
  <Repository>vansmak/episeerr:latest</Repository>
  <Registry>https://hub.docker.com/r/vansmak/episeerr</Registry>
  <Network>bridge</Network>
  <Shell>sh</Shell>
  <Privileged>false</Privileged>
  <Support>https://github.com/Vansmak/episeerr/issues</Support>
  <Project>https://github.com/Vansmak/episeerr</Project>
  <Overview>Smart episode management for Sonarr</Overview>
  <Category>MediaApp:Video</Category>
  <WebUI>http://[IP]:[PORT:5002]</WebUI>
  <Icon>https://raw.githubusercontent.com/Vansmak/episeerr/main/static/logo_icon.png</Icon>
  
  <Config Name="WebUI Port" Target="5002" Default="5002" Mode="tcp" Description="Episeerr WebUI" Type="Port" Display="always" Required="true" Mask="false"/>
  
  <Config Name="Config" Target="/app/config" Default="/mnt/user/appdata/episeerr/config" Mode="rw" Description="Configuration files" Type="Path" Display="always" Required="true" Mask="false"/>
  <Config Name="Logs" Target="/app/logs" Default="/mnt/user/appdata/episeerr/logs" Mode="rw" Description="Log files" Type="Path" Display="always" Required="true" Mask="false"/>
  <Config Name="Data" Target="/app/data" Default="/mnt/user/appdata/episeerr/data" Mode="rw" Description="Database files" Type="Path" Display="always" Required="true" Mask="false"/>
  <Config Name="Temp" Target="/app/temp" Default="/mnt/user/appdata/episeerr/temp" Mode="rw" Description="Temporary files" Type="Path" Display="always" Required="false" Mask="false"/>
  
  <Config Name="SONARR_URL" Target="SONARR_URL" Default="" Description="Sonarr base URL (e.g., http://sonarr:8989)" Type="Variable" Display="always" Required="true" Mask="false"/>
  <Config Name="SONARR_API_KEY" Target="SONARR_API_KEY" Default="" Description="Sonarr API key" Type="Variable" Display="always" Required="true" Mask="true"/>
  <Config Name="TMDB_API_KEY" Target="TMDB_API_KEY" Default="" Description="TMDB Read Access Token (not API key)" Type="Variable" Display="always" Required="true" Mask="true"/>
  
  <Config Name="TAUTULLI_URL" Target="TAUTULLI_URL" Default="" Description="Tautulli URL (optional)" Type="Variable" Display="always" Required="false" Mask="false"/>
  <Config Name="TAUTULLI_API_KEY" Target="TAUTULLI_API_KEY" Default="" Description="Tautulli API Key (optional)" Type="Variable" Display="always" Required="false" Mask="true"/>
  
  <Config Name="JELLYFIN_URL" Target="JELLYFIN_URL" Default="" Description="Jellyfin URL (optional)" Type="Variable" Display="always" Required="false" Mask="false"/>
  <Config Name="JELLYFIN_API_KEY" Target="JELLYFIN_API_KEY" Default="" Description="Jellyfin API Key (optional)" Type="Variable" Display="always" Required="false" Mask="true"/>
  <Config Name="JELLYFIN_USER_ID" Target="JELLYFIN_USER_ID" Default="" Description="Jellyfin Username (required if using Jellyfin)" Type="Variable" Display="always" Required="false" Mask="false"/>
  
  <Config Name="JELLYSEERR_URL" Target="JELLYSEERR_URL" Default="" Description="Jellyseerr URL (optional)" Type="Variable" Display="always" Required="false" Mask="false"/>
  <Config Name="JELLYSEERR_API_KEY" Target="JELLYSEERR_API_KEY" Default="" Description="Jellyseerr API Key (optional)" Type="Variable" Display="always" Required="false" Mask="true"/>
</Container>

2. Install from Apps

Unraid → Apps
Search "episeerr"
Click Install
Fill in required fields

GUI Setup Page (v3.2.0+)

The easiest way to configure Episeerr - no .env file needed!

Access: http://your-server:5002/setup

Configure:

Sonarr - URL and API key (required) Initial setup Restart container for changes to take effect
TMDB - API Read Access Token (required)
Media Server - Choose Plex, Jellyfin, or Emby (optional — needed for viewing automation)
Overseerr/Jellyseerr - Request integration (optional)

Features:

✅ Test connections before saving
✅ Configuration stored in database
✅ Auto-populate Quick Links in sidebar
✅ No container restart needed
✅ Works alongside .env files (database takes priority)

Migration from .env:

Open /setup page
Your existing .env values appear as defaults
Save to migrate to database
Delete .env file when ready

Environment Variables

Note: As of v3.2.0, environment variables are optional. You can configure everything via the /setup page GUI. Environment variables still work for backward compatibility and can be used alongside database configuration (database takes priority).

Variable	Required	Description
`SONARR_URL`	❌ Optional*	Sonarr base URL (e.g., `http://sonarr:8989`)
`SONARR_API_KEY`	❌ Optional*	Sonarr API key (Settings → General)
`TMDB_API_KEY`	❌ Optional*	TMDB Read Access Token (Get one free)
`PLEX_URL`	❌ Optional	Plex server URL (e.g. `http://plex:32400`)
`PLEX_TOKEN`	❌ Optional	Plex authentication token
`TAUTULLI_URL`	❌ Optional	Tautulli — only needed for watch-history override or if you don't have Plex Pass
`TAUTULLI_API_KEY`	❌ Optional	Tautulli API key
`JELLYFIN_URL`	❌ Optional	For Jellyfin viewing automation
`JELLYFIN_API_KEY`	❌ Optional	Jellyfin API key
`JELLYFIN_USER_ID`	⚠️ Required if using Jellyfin	Your Jellyfin username
`EMBY_URL`	❌ Optional	For Emby viewing automation
`EMBY_API_KEY`	❌ Optional	Emby API key
`EMBY_USER_ID`	⚠️ Required if using Emby	Your Emby username
`JELLYSEERR_URL`	❌ Optional	For request integration
`JELLYSEERR_API_KEY`	❌ Optional	Jellyseerr API key

Authentication (Optional):

Variable	Default	Description
`REQUIRE_AUTH`	`false`	Enable password authentication
`AUTH_USERNAME`	`admin`	Login username
`AUTH_PASSWORD`	-	Login password (required if auth enabled)
`SECRET_KEY`	Auto-generated	Session encryption key (optional, auto-generated if not set)
`AUTH_BYPASS_LOCALHOST`	`true`	Skip authentication for localhost access
`AUTH_SESSION_TIMEOUT`	`86400`	Session timeout in seconds (24 hours)

⚠️ Important Notes:

TMDB requires the Read Access Token, not the API key v3
Jellyfin requires JELLYFIN_USER_ID to be set to your username
All URLs should NOT have trailing slashes
Security: If exposing Episeerr beyond your local network, enable REQUIRE_AUTH or use a reverse proxy with authentication (Cloudflare Access, Authelia, etc.)

Dashboard Integrations Overview Episeerr's beta plugin system allows you to connect additional services that display statistics on your dashboard. Services are configured through the Setup page and automatically appear once configured. Available Integrations

Example, Radarr: Movie library management

Displays total movies and storage usage Shows monitored vs total counts

Setup Process

Navigate to Setup: Go to the Setup page (/setup) Find Integration: Scroll to "Dashboard Integrations" section Configure Service:

URL: Full service URL including http:// or https:// API Key: Found in service settings (usually under Settings > General)

Test Connection: Click "Test" button to verify Save: Click "Save" to store configuration Restart: Restart the Episeerr container Verify: Check Dashboard for new statistics pill Quick Link: Service link automatically appears in sidebar

Important Notes

Container restart required after initial configuration Configuration persists across restarts Services can be reconfigured at any time through Setup page Invalid configurations won't crash the dashboard - they simply won't display

Creating Custom Integrations Advanced users can create custom integrations for any service with an API:

Copy Template: Start with /integrations/_INTEGRATION_TEMPLATE.py Customize: Fill in service details, API calls, and widget configuration Save: Name file yourservice.py (no underscore prefix) Restart: Restart container to load new integration Configure: Service automatically appears in Setup page

The template includes extensive documentation and examples for:

Media library services (similar to Radarr) Download clients (qBittorrent, Transmission, etc.) Indexers and search services (Prowlarr, Jackett, etc.) Custom services with unique requirements

Plex Watchlist Sync

Add something to your Plex watchlist and Episeerr takes care of the rest.

TV shows → get the episeerr_select tag in Sonarr → appear in Pending Requests → you pick a rule or specific episodes before anything downloads
Movies → go straight to Radarr (no selection step needed)

Optional: Auto-remove movies from Radarr after you've watched them, with a configurable grace period.

Setup

Go to http://your-server:5002/setup
Scroll to the Plex section under Dashboard Integrations
Enter your Plex URL (e.g., http://plex:32400) and Plex Token
In the Watchlist Auto-Sync section below the connection fields:
- Enable automatic sync
- Set your sync interval (default: 2 hours)
- Optionally enable movie cleanup with a grace period
Click Save

Prerequisites: The episeerr_select delayed release profile in Sonarr must be set up or TV shows will start downloading immediately. See Episode Selection setup.

Getting Your Plex Token

A helper script is included in the repo. It requires the requests library.

python get_plex_token.py

Enter your Plex username (not email) and password when prompted. The token printed works for both local server access and the Plex.tv watchlist API.

Manual method (no script):

Sign in to plex.tv in a browser
Open any media item
Click the ··· menu → Get Info
In the URL bar you'll find X-Plex-Token=YOURTOKEN

How It Works

What You Do	What Episeerr Does
Add TV show to Plex watchlist	Creates a pending selection request, tags series in Sonarr with `episeerr_select`
Add movie to Plex watchlist	Sends directly to Radarr
Watch a movie (if cleanup enabled)	Schedules Radarr deletion after grace period

Sync runs on your configured interval. Items already in Sonarr/Radarr are skipped. Items already in your pending requests are not duplicated.

Movie Cleanup

When Delete movies after watched is enabled:

Episeerr checks for watched movies in your Plex library
Movies watched more than Grace Period days ago are removed from Radarr
Only movies that were added via watchlist sync are eligible

Webhook Setup

Webhooks let Episeerr respond to events automatically. You only need the webhooks for features you want to use.

1. Sonarr Webhook (Required)

Enables: Tag processing, auto-assignment, series addition detection

Setup:

Sonarr → Settings → Connect → Add → Webhook
Configure:
- Name: Episeerr
- URL: http://your-episeerr:5002/sonarr-webhook
- Method: POST
- Triggers: Enable ONLY "On Series Add" and "on Grab"
Save

Test it:

docker logs episeerr | grep "Received Sonarr webhook"

2. Plex Webhook (For Viewing Automation — Plex Pass required)

Enables: Next episode ready when you watch, dashboard "Now Playing" widget

Episeerr now integrates with Plex directly — no Tautulli required for episode detection.

⚠️ Plex OR Tautulli for episode detection — not both. Configure one webhook source per setup. Using both can cause double-processing.

Setup:

Go to http://your-episeerr:5002/setup → Integrations → Plex
Enter your Plex Server URL and Plex Token (how to get token)
Choose your Detection Method (see table below)
Click Test then Save

In Plex:

Plex Web / Desktop → Settings → Webhooks → Add Webhook
URL: http://your-episeerr:5002/api/integration/plex/webhook

Detection Modes:

Mode	How It Works	Best For
Scrobble (90%)	Plex fires its native "watched" event. Episeerr processes immediately.	Simple setup, reliable
Stop + Threshold	Process when you stop at ≥ your % (e.g. 50%). Scrobble fires at 90% as a safety net if the stop event is missed. Episodes are never double-processed.	Earlier triggering, no polling
Polling	Background thread polls `/status/sessions` every N minutes.	Unreliable webhook environments

Allowed Users (optional): Enter comma-separated Plex usernames in setup to restrict processing to specific accounts. Leave blank for all users.

Test it:

docker logs episeerr | grep "\[Plex webhook\]"

2b. Tautulli Webhook (Optional — Plex users who prefer Tautulli history)

Tautulli is now optional. Use it only if you want richer watch history from Tautulli instead of Plex's native API (e.g. for grace period and dormant detection accuracy).

⚠️ If you use Plex native webhooks (above), do NOT also set up a Tautulli "Watched" webhook. Tautulli's "Watched" webhook and Plex's scrobble/stop webhooks both trigger episode processing — running both will cause double downloads.

When to use Tautulli:

You want Tautulli's richer per-user watch history for grace period / dormant decisions
You don't have Plex Pass (no native webhooks available)

Setup:

Go to http://your-episeerr:5002/setup → Integrations → Tautulli
Enter Tautulli URL and API Key
Optionally enable "Use Tautulli for watch history" — routes all watch-date lookups (grace, dormant) through Tautulli
Click Test then Save

Tautulli Webhook (only if using Tautulli for episode detection):

Tautulli → Settings → Notification Agents → Add → Webhook
Configure:
- Webhook URL: http://your-episeerr:5002/api/integration/tautulli/webhook
- Method: POST
- Trigger: "Watched"

Data → Text:

{
  "plex_title": "{show_name}",
  "plex_season_num": "{season_num}",
  "plex_ep_num": "{episode_num}",
  "thetvdb_id": "{thetvdb_id}",
  "themoviedb_id": "{themoviedb_id}",
  "notification_type": "{notification_type}"
}

Save

Legacy URL: /webhook still works if you have an existing Tautulli setup — no changes needed.

Optional: Playback Start activation (for + modifier rules)

If you use the + activation modifier (s*e1+, e1+, etc.) and want the hold released the moment you press play rather than after the watch threshold, add a second notification agent:

Tautulli → Settings → Notification Agents → Add → Webhook
Configure:
- Webhook URL: http://your-episeerr:5002/api/integration/tautulli/webhook
- Method: POST
- Trigger: "Playback Start"

Data → Text: (same template as above — notification_type is what tells Episeerr this is a play-start event)

{
  "plex_title": "{show_name}",
  "plex_season_num": "{season_num}",
  "plex_ep_num": "{episode_num}",
  "thetvdb_id": "{thetvdb_id}",
  "themoviedb_id": "{themoviedb_id}",
  "notification_type": "{notification_type}"
}

Save

For non-held series (no + modifier), playback start events are silently ignored — no risk of double-processing.

In Tautulli → Settings → General, set TV Episode Watched Percent between 50–95% (recommended: 80%).

3. Jellyfin Webhook (For Viewing Automation)

Enables: Next episode ready when you watch

Episeerr supports two modes for Jellyfin — pick one:

Configuration (for both modes):

Option 1: Setup Page (Recommended) - v3.2.0+

Go to http://your-episeerr:5002/setup
Scroll to Jellyfin section
Choose your mode and enter settings accordingly
Click Test Connection to verify
Save

Option 2: Environment Variables - See each mode below for specific variables

Mode A: Real-Time (Recommended)

Jellyfin sends a webhook on every progress update. Episeerr fires once when progress lands in the 50–55% window. No polling needed.

Webhook Setup:

Jellyfin → Dashboard → Plugins → Webhooks → Add Generic Destination
Configure:
- Webhook Name: Episeerr Episode Tracking
- Webhook URL: http://your-episeerr:5002/api/integration/jellyfin/webhook
- Notification Type: Select ONLY "Playback Progress"
- User Filter: Your username (recommended)
- Item Type: Episodes
- Send All Properties: ✅ Enabled
Save

Environment Variables (if not using Setup Page):

- JELLYFIN_URL=http://your-jellyfin:8096
- JELLYFIN_API_KEY=your_api_key
- JELLYFIN_USER_ID=your_username  # REQUIRED
- JELLYFIN_TRIGGER_MIN=50.0
- JELLYFIN_TRIGGER_MAX=55.0

[Jellyfin webhook plugin configuration]
[Shows Playback Progress selected]
[Shows User Filter field]

Mode B: Polling

Jellyfin sends a webhook on session start. Episeerr then polls the Jellyfin /Sessions API every 15 minutes until the trigger percentage is hit. Useful if PlaybackProgress webhooks are unreliable on your setup.

Webhook Setup:

Jellyfin → Dashboard → Plugins → Webhooks → Add Generic Destination
Configure:
- Webhook URL: http://your-episeerr:5002/api/integration/jellyfin/webhook
- Notification Type: Select "Session Start"
- User Filter: Your username
- Item Type: Episodes

Environment Variables (if not using Setup Page):

- JELLYFIN_URL=http://your-jellyfin:8096
- JELLYFIN_API_KEY=your_api_key
- JELLYFIN_USER_ID=your_username  # REQUIRED
- JELLYFIN_TRIGGER_PERCENTAGE=50.0
- JELLYFIN_POLL_INTERVAL=900  # seconds (15 minutes)

Which Jellyfin mode should you use?

Option	Best For	Processing	Jellyfin Webhooks Needed
A: Real-Time	Most users	Immediate at 50–55%	PlaybackProgress (continuous)
B: Polling	Unreliable progress webhooks	Up to 15-min delay	Session Start (one-shot)

Test it:

# Watch an episode past 50% and check logs
docker logs episeerr | grep "Processing Jellyfin"

4. Emby Webhook (For Viewing Automation)

Enables: Next episode ready when you watch

Emby doesn't send continuous progress webhooks like Jellyfin's PlaybackProgress, so Episeerr uses polling only. On playback.start, Episeerr spawns a background thread that queries the Emby /Sessions API every 15 minutes until your watch progress hits the trigger threshold. This handles autoplay correctly — if E1 finishes and E2 auto-starts without a playback.stop firing for E1, the poll already caught E1 at 50% and triggered the next episode search.

Configuration:

Option 1: Setup Page (Recommended) - v3.2.0+

Go to http://your-episeerr:5002/setup
Scroll to Emby section
Enter:
- Emby URL (e.g., http://emby:8096)
- API Key (from Emby → Settings → Advanced → Security)
- Username (must match the user watching content)
- Trigger Percentage (default: 50.0%)
- Poll Interval (default: 900 seconds / 15 minutes)
Click Test Connection to verify
Save

Option 2: Environment Variables

- EMBY_URL=http://your-emby:8096
- EMBY_API_KEY=your_emby_api_key
- EMBY_USER_ID=your_username  # REQUIRED — must match the Emby user
- EMBY_TRIGGER_PERCENTAGE=50.0
- EMBY_POLL_INTERVAL=900  # seconds (15 minutes)

Webhook Setup:

Emby → User Preferences (top-right avatar) → Notifications → Webhooks → Add Webhook
Configure:
- Webhook Name: Episeerr Episode Tracking
- Webhook URL: http://your-episeerr:5002/api/integration/emby/webhook
- Events: Enable "playback.start" and "playback.stop"
- (No item type filter in Emby — it sends all events; Episeerr filters to Episodes internally)
Save

Note: The webhook is configured per-user in Emby, not server-wide like Jellyfin's plugin. Make sure you're configuring it for the user account that watches content.

Test it:

# Watch an episode past 50% and check logs
docker logs episeerr | grep "Processing Emby"

How it works:

Event	What Episeerr Does
`playback.start`	Starts polling `/Sessions` for this session every `POLL_INTERVAL` seconds
Poll hits `TRIGGER_PERCENTAGE`	Fires episode processing, marks session as handled
`playback.stop`	Stops the polling thread. If already processed by poll, skips. If not yet hit threshold, checks final position one last time.

Test it:

# Watch an episode past 50% and check logs
docker logs episeerr | grep "Processing Emby"

4. Jellyseerr/Overseerr Webhook (Optional)

Enables: Season-specific automation with direct rule tags

What it does:

Captures which season you requested
Allows rules to start from that season (not Season 1)

Setup:

Jellyseerr/Overseerr → Settings → Notifications → Webhooks
Add Webhook:
- Webhook URL: http://your-episeerr:5002/api/integration/seerr/webhook
- Notification Types: Enable "Request Approved"
Save

[Jellyseerr webhook configuration]
[Shows URL field and Request Approved checkbox]

Test it:

# Request a series in Jellyseerr and check logs
docker logs episeerr | grep "Stored.*request"

How to Use

Create Your First Rule

Rules control what happens when you watch episodes.

Open Episeerr: http://your-server:5002
Go to Rules → Create New Rule

Configure:

Setting	What It Does	Example
Name	Rule identifier	"binge_watcher"
GET	Episodes to prepare	"3 episodes" = next 3 ready
KEEP	Episodes to retain	"1 episode" = keep only last watched
Action	Monitor or Search	"Search" = actively download

Optional Time-Based Cleanup:

Setting	What It Does	Example
Grace Watched	Delete old watched episodes after X days	"7 days"
Grace Unwatched	Delete unwatched episodes after X days	"14 days"
Dormant	Delete everything after X days inactive	"30 days"

Mark as Default Rule (if this is your main rule)
Save

[Rule creation form showing all fields]
[Example configuration for binge watcher]

Adding Series

There are three paths into Episeerr, each with different behavior.

Path 1: From outside Episeerr (Sonarr, Seerr, nzb360, etc.)

Episeerr intercepts series added to Sonarr via tags on the Sonarr webhook.

Tag	What happens
`episeerr_<rulename>`	Processed immediately with that rule — GET/monitor applied, tag removed
`episeerr_select`	Pending request created, delay profile holds all downloads until you confirm selections
(no tag, auto-assign on)	Silently added to default rule, waits for first watch before doing anything

episeerr_select requires a Sonarr delay profile to hold downloads until you make your selection — see Episode Selection setup below.

Use cases: Add from Sonarr UI, request from Jellyseerr/Overseerr, add from nzb360

Path 2: Plex Watchlist Sync

Enable Plex Watchlist Sync on the Setup page
Add a show or movie to your Plex watchlist
On the next sync cycle:
- TV shows → added to Sonarr with episeerr_select tag → pending request created
- Movies → sent directly to Radarr

Use case: Browse Plex Discover, add to watchlist, Episeerr handles the rest

Path 3: Search within Episeerr

Use the search bar in Episeerr to find a TV show by name
Click Add on the result
The season/rule selection screen opens immediately — nothing has been written to Sonarr yet
Choose a rule and/or select specific seasons/episodes
Click Apply Rule or Submit — only then does Episeerr add the series to Sonarr and update your Plex watchlist
Cancel at any point → nothing is added anywhere

No episeerr_select tag or delay profile needed — Episeerr drives the whole flow directly.

Movies added via search go straight to Radarr with your default quality profile and root folder, and are added to your Plex watchlist immediately.

Existing series: manual assignment

For series already in Sonarr — go to Episeerr → Series Management, select a series, choose a rule, and assign.

Episode Selection

Choose specific episodes manually across seasons — or just pick a rule.

One-time Sonarr setup (required for Path 1 and Path 2 only):

Without this, external adds with episeerr_select will start downloading immediately before you make your selection.

Sonarr → Settings → Profiles → Release Profiles → Add
Configure:
- Name: Episeerr Episode Selection Delay
- Delay: 10519200 (20 years)
- Tags: episeerr_select
Save

Not needed for Path 3 (search within Episeerr) — Sonarr isn't touched until after you confirm.

Entering the selection flow:

How	Entry point
Search within Episeerr → Add	Goes directly to selection screen
Plex watchlist sync (TV)	Appears in Pending Items → click Select
Add to Sonarr with `episeerr_select` tag	Appears in Pending Items → click Select
Any series already in Sonarr	Click the list icon on the poster or in Series Management

Selection Flow and Rule Picker

The season selection page shows a rule dropdown at the top regardless of how you arrived.

Option	What It Does
Apply Rule	Assigns the rule — rule's GET logic runs immediately, ongoing management from there
Select seasons/episodes manually	Pick exactly what to download; selected rule still handles ongoing management

Cancel → deletes the pending request, nothing is added to Sonarr or Plex watchlist.

The rule dropdown pre-selects the show's current rule if it already has one — so re-routing a series is a one-click change.

Features Explained

🔄 Plex Watchlist Sync

Hands-off adding from your Plex watchlist.

Use cases:

Browse Plex Discover and add without touching Sonarr
Automatic movie requests to Radarr
Clean up watched movies automatically

How it works:

Add show/movie to Plex watchlist
Episeerr polls on your configured interval
TV → pending selection request + episeerr_select tag in Sonarr
Movie → sent directly to Radarr
(Optional) Watched movies removed from Radarr after grace period

🎯 Episode Selection

Manual episode picking across multiple seasons.

Use cases:

Try pilots without downloading full seasons
Skip filler episodes
Download specific arcs
Selective backlog management
Re-route an existing series to a different rule

How it works:

Series enters selection flow (tag, watchlist sync, or series page icon)
Season selection page appears with a rule picker at the top
Either apply a rule directly (no manual picking needed), or choose specific episodes below
Only selected episodes download; the chosen rule handles ongoing management

📌 Always Have (Rule Parameter)

Define a baseline of episodes that are always present and protected from cleanup.

This is about setting up the show, not ongoing watching. When a show enters a rule with Always Have, those episodes get downloaded immediately. Grace and Keep cleanup will never touch them — only Dormant (which is intentionally nuclear) overrides this.

Base expressions:

Expression	Result
`s1e1`	Just the pilot
`s1`	All of season 1
`s1, s*e1`	Season 1 + first ep of every other season
`s1-3`	Seasons 1 through 3
`s1e1-5`	Season 1, episodes 1-5
`all`	Everything

Modifiers (append to any base expression):

Expression	Behaviour
`s*e1`	Grab & permanently keep E1 of every season (default)
`s*e1-`	Grab E1 of every season; follows grace/keep rules after watched
`s*e1+`	Per-season activation gate — get-count held at 0 until E1 playback starts
`s*e1+-`	Per-season gate + E1 removable after activation
`e1+`	Sequential: grab one season at a time, advance on finale
`s1e1+`	Activation gate on pilot only; full auto from S2
`pilot+`	Alias for `e1+`

+ — suppresses get-count until the activation episode starts playing (per-season state); fires on playback start across Plex, Jellyfin, Emby, and Tautulli
- — activation episode is removable by grace/keep after activation fires

Combine with commas. Leave blank to skip. Always Have, Get, Keep, Grace, and Dormant are all independent — use any combination.

⚡ Viewing Automation

Next episode ready when you watch.

Use cases:

Binge watching (always 2-3 episodes ahead)
Weekly shows (stay current)
Automatic queue management

How it works:

Watch S1E5
Webhook fires to Episeerr
Rule applied: GET next 2 episodes
S1E6, S1E7 now monitored/searched
KEEP rule: Delete S1E1-S1E4 (outside keep window)

Example flow:

Watch E5 → Get E6, E7 → Keep E5 → Delete E1-E4

💾 Storage Management

Automatic cleanup based on time and viewing activity.

Use cases:

Limited storage (seedboxes, budget servers)
Inactive show cleanup
Abandoned series removal

How it works:

Cleanup Type	Trigger	What It Does
Grace Watched	X days inactive	Deletes old watched episodes, keeps last as bookmark
Grace Unwatched	X days inactive	Deletes unwatched episodes, keeps first as bookmark
Dormant	X days + low storage	Deletes EVERYTHING from abandoned shows

Storage Gate:

Set threshold: "Keep 20GB free"
Cleanup only runs when below threshold
Stops when back above threshold

Bookmarks:

Grace cleanup ALWAYS keeps at least 1 episode
You never lose your viewing position

Configuration Examples

Binge Watcher

Profile: Always 3 episodes ahead, aggressive cleanup

Rule Name: binge_watcher
GET: 3 episodes
KEEP: 1 episode
Action: Search
Grace Watched: 7 days
Grace Unwatched: 14 days
Dormant: 30 days

What happens:

Watch E5 → E6, E7, E8 ready
Keep E5, delete E1-E4
After 7 days inactive → Delete E5 (keeps bookmark)
After 30 days → Delete entire show

Current Shows

Profile: Stay current, keep buffer

Rule Name: weekly
GET: 1 episode
KEEP: 3 episodes
Action: Monitor
Grace Watched: 30 days
Grace Unwatched: null
Dormant: 90 days

What happens:

Watch E5 → E6 monitored
Keep E3, E4, E5
After 30 days → Cleanup old episodes
Unwatched episodes never auto-deleted

Protected Series

Profile: Never delete, keep everything

Rule Name: protected
GET: All
KEEP: All
Action: Search
Grace Watched: null
Grace Unwatched: null
Dormant: null

What happens:

Watch E5 → All future episodes monitored
Nothing ever deleted
Perfect for rewatchable favorites

Season Binger

Profile: Watch whole seasons, rotate

Rule Name: season_binger
GET: 1 season
KEEP: 1 season
Action: Search
Grace Watched: 14 days
Grace Unwatched: null
Dormant: 90 days

What happens:

Watch S2E1 → All of S3 monitored
Keep all of S2, delete S1
After 14 days → Cleanup S2
Perfect for binging complete seasons

Showcase

Profile: Plex shows all seasons exist without downloading everything

Rule Name: showcase
Always Have: s1, s*e1
GET: 1 episode
KEEP: 1 episode
Action: Search
Grace Watched: null
Grace Unwatched: null
Dormant: null

What happens:

Show added → Season 1 downloads + first episode of every other season
Plex displays all seasons so users see the full scope of the show
When someone starts watching → Get 1 brings the next episode
Always Have episodes never get deleted by Keep or Grace
No cleanup configured — show persists as a library placeholder

One-at-a-Time with Pilot

Profile: Minimal footprint, always keep a starting point

Rule Name: one_at_a_time
Always Have: s1e1
GET: 1 episode
KEEP: 1 episode
Action: Search
Keep Pilot: true
Grace Watched: 14 days
Dormant: 60 days

What happens:

Pilot is always protected (Always Have + Keep Pilot)
Watch E5 → E6 ready, E4 deleted
After 14 days inactive → Cleanup watched, pilot stays
After 60 days dormant → Everything deleted including pilot

Sequential Activation (one season at a time)

Profile: Grab only the current season; unlock the next when the finale is watched

Rule Name: sequential
Always Have: e1+
GET: 1 episode
KEEP: 1 episode
Action: Search

What happens:

Show added → S1E1 downloaded, get-count held at 0 until S1E1 starts playing
Press play on S1E1 → activation fires immediately, get-count unlocked, normal Get/Keep applies
Watch S1 finale → S2E1 grabbed, get-count held again until S2E1 starts playing
Ended series: does not advance past the final season

Troubleshooting

Container Won't Start

Check:

docker logs episeerr

Common issues:

Missing required environment variables
Invalid Sonarr URL format (remove trailing slash)
Wrong TMDB key type (need Read Access Token, not API key)

Fix:

# Correct format:
- SONARR_URL=http://sonarr:8989  # No trailing slash
- TMDB_API_KEY=eyJhbG...  # Read Access Token (long string)

Webhooks Not Working

Test webhook reception:

# Watch logs live
docker logs -f episeerr | grep webhook

# Check recent webhook events
docker logs episeerr | grep "Received.*webhook" | tail -20

Common issues:

Problem	Check	Solution
No webhooks received	Network connectivity	Can webhook sender reach Episeerr?
Webhooks received but nothing happens	Series assignment	Is series in a rule?
Wrong episodes managed	Webhook data	Check logs for series name matching

Verify webhook URLs:

Sonarr: http://episeerr:5002/sonarr-webhook
Tautulli: http://episeerr:5002/webhook
Jellyfin: http://episeerr:5002/api/integration/jellyfin/webhook
Emby: http://episeerr:5002/api/integration/emby/webhook
Jellyseerr: http://episeerr:5002/api/integration/seerr/webhook

Configuration: Use the /setup page to configure services with URLs and API keys (recommended), or use environment variables.

Episodes Not Monitoring

Check series assignment:

Episeerr → Series Management

Verify:

Series is listed under a rule
Rule has GET settings configured
Watch an episode to trigger

Manual trigger:

# Watch an episode, then check logs
docker logs episeerr | grep "Monitored.*episodes"

Tags Not Working

For direct rule tags (episeerr_binge_watcher):

Verify tag exists in Sonarr:
- Sonarr → Settings → Tags
- Tag must match rule name exactly
Check Sonarr webhook:
- Settings → Connect → Webhook
- URL: http://episeerr:5002/sonarr-webhook
- Trigger: "On Series Add" enabled

Check logs:

docker logs episeerr | grep "Processing.*with tag"

Jellyfin Not Working

Most common issue: Missing JELLYFIN_USER_ID

# REQUIRED for Jellyfin
- JELLYFIN_USER_ID=your_username  # This is your Jellyfin login name

Check webhook plugin:

Jellyfin → Dashboard → Plugins → Webhooks

Verify:

Webhook URL is correct
Proper notification types selected
User filter matches your username

Test:

# Watch episode past 50% and check logs
docker logs episeerr | grep "Jellyfin"

Screenshots

FAQ

Plex Watchlist Sync

Q: Do I need Tautulli for Plex watchlist sync? A: No. Watchlist sync uses the Plex.tv API directly with your Plex token — Tautulli is only needed for viewing automation (next episode ready when you watch).

Q: Where do I get my Plex token? A: Run python get_plex_token.py from the repo. Enter your Plex username (not email) and password. See Getting Your Plex Token for a manual method too.

Q: Why does my username not work in get_plex_token.py? A: Use your Plex username, not your email address. Check your username at plex.tv/account.

Q: TV shows from my watchlist aren't downloading automatically — is that right? A: Yes, by design. TV shows get the episeerr_select tag and land in Pending Requests so you can choose a rule or pick specific episodes first. Movies go straight to Radarr with no selection step.

Q: Can I change the sync interval? A: Yes — Setup page → Plex section → Sync Interval. Options range from 30 minutes to 24 hours.

General

Q: Do I need all the webhooks?
A: No! Only set up webhooks for features you want:

Episode Selection only: Sonarr webhook
Viewing Automation: Sonarr + Tautulli/Jellyfin webhooks
Full automation: All webhooks

Q: What does Always Have do?
A: It's an expression on a rule that defines episodes to always keep. When a show enters the rule, those episodes get downloaded immediately. Grace and Keep cleanup won't delete them. Only Dormant (which is intentionally nuclear) overrides it. Add + to create an activation gate (get-count held until the episode is watched) or - to make the episode removable after it's watched.

Q: Does Always Have apply when I move a show to a different rule?
A: Yes. Whether it's a new show or a reassignment, the Always Have expression runs and ensures those episodes are monitored.

Q: Will Always Have re-download episodes I deleted manually?
A: Not automatically. Always Have runs on rule assignment and protects during cleanup. It doesn't continuously scan for missing episodes.

Q: Can I use both Tautulli and Jellyfin?
A: No need - choose one based on your media server (Plex = Tautulli, Jellyfin = Jellyfin webhook)

Q: What's the difference between tags and auto-assign?
A:

Tags (episeerr_[rule_name]): Immediate processing with specific rules
Auto-assign: Passive assignment, waits for first watch

Q: Will this download my entire library?
A: No! Only series assigned to rules are managed. Use episode selection or auto-assign to control what gets managed.

Tags & Assignment

Q: Why did my tag disappear?
A: Tags are temporary signals. After processing, the tag is removed. Check Series Management to verify assignment succeeded.

Q: How do I use tags for specific rules?
A: Tag format is episeerr_[rule_name]. If you have a rule named "binge_watcher", use tag episeerr_binge_watcher.

Q: Can I change which rule a series uses?
A: Yes! Either:

Change tag in Sonarr (tag drift detection will update Episeerr)
Manually reassign in Series Management

Viewing Automation

Q: Episodes aren't updating when I watch?
A: Check:

Is viewing webhook configured? (Tautulli or Jellyfin)
Is series assigned to a rule?
Check logs: docker logs episeerr | grep webhook

Q: How much do I need to watch for it to trigger?
A:

Tautulli: Set in Tautulli settings (50-95%, recommended 80%)
Jellyfin: 50% by default (configurable via JELLYFIN_TRIGGER_PERCENTAGE)

Q: Can different people watch different seasons?
A: Yes! Enable "Grace Period Scope: Per Season" in rule settings for independent season tracking.

Deletions

Q: Will I lose my place if episodes get deleted?
A: No! Grace cleanup always keeps:

Grace Watched: Last watched episode (bookmark)
Grace Unwatched: First unwatched episode (resume point)

Q: How do I test without deleting anything?
A: Enable "Global Dry Run Mode" in Settings. Review deletions in Pending Deletions before approving.

Q: Why are episodes being deleted immediately?
A: KEEP rule deletes in real-time when watching. This is by design. To prevent this:

Increase KEEP count
Or disable KEEP entirely (set to "All")

Q: What's the difference between Grace and Dormant?
A:

Grace: Time-based cleanup of specific episode types (watched/unwatched)
Dormant: Nuclear option - deletes EVERYTHING from completely abandoned shows

Jellyfin Specific

Q: Which Jellyfin mode should I use?
A: Real-time (Playback Progress) for most users. Use polling if you have webhook reliability issues.

Q: Do I need to disable any modes?
A: No! System auto-detects based on environment variables. Just set the vars for your chosen mode.

Q: JELLYFIN_USER_ID - What do I put here?
A: Your Jellyfin username (the name you use to log in). This is REQUIRED for Jellyfin integration.

Storage Management

Q: How do I set up storage cleanup?
A: Settings → Global Settings → Set "Storage Threshold" (e.g., 20GB). Cleanup only runs when below threshold.

Q: Will it delete shows I'm actively watching?
A: No! Grace periods reset when you watch episodes. Only inactive shows are cleaned up.

Q: Can I protect certain shows?
A: Yes! Create a rule with empty Grace and Dormant settings, assign those shows to it.

Support

Get Help

📖 In-App Documentation: http://your-episeerr:5002/documentation
🐛 Report Issues: GitHub Issues
💬 Discussions: GitHub Discussions
☕ Support Development: Buy Me A Coffee

Logs Location

# Docker
docker logs episeerr

# Logs directory
./logs/app.log

# Live monitoring
docker logs -f episeerr

Common Log Searches

# Check webhook reception
docker logs episeerr | grep "Received.*webhook"

# Check rule processing
docker logs episeerr | grep "Monitored.*episodes"

# Check errors
docker logs episeerr | grep "Error\|Failed"

# Check specific series
docker logs episeerr | grep "Breaking Bad"

Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

License

MIT License

Acknowledgments

Built with AI assistance as a development tool. All architecture, design decisions, and problem-solving are human-driven. Code is open source for transparency and community review.

Ready to get started? Jump to Quick Start ⬆️

Name		Name	Last commit message	Last commit date
Latest commit History 384 Commits
integrations		integrations
static		static
templates		templates
.dockerignore		.dockerignore
.envexample		.envexample
.gitignore		.gitignore
BACKLOG.md		BACKLOG.md
CHANGELOG.md		CHANGELOG.md
CHANGELOG_OLD.md		CHANGELOG_OLD.md
Dockerfile		Dockerfile
README.md		README.md
VERSION		VERSION
activity_storage.py		activity_storage.py
dashboard.py		dashboard.py
dev		dev
docker-compose.yml		docker-compose.yml
episeerr.py		episeerr.py
episeerr_utils.py		episeerr_utils.py
funding-gate.svg		funding-gate.svg
get_plex_token.py		get_plex_token.py
logging_config.py		logging_config.py
media_processor.py		media_processor.py
notification_storage.py		notification_storage.py
notifications.py		notifications.py
ocdarr.png		ocdarr.png
pending_deletions.py		pending_deletions.py
release.sh		release.sh
requirements.txt		requirements.txt
settings_db.py		settings_db.py
sonarr_utils.py		sonarr_utils.py
webhooks.py		webhooks.py

Folders and files

Latest commit

History

Repository files navigation

Episeerr

📋 Table of Contents

What It Does

Quick Start

Installation

Two Ways to Configure:

Docker Compose (Recommended)

Unraid Untested by me

GUI Setup Page (v3.2.0+)

Environment Variables

Plex Watchlist Sync

Setup

Getting Your Plex Token

How It Works

Movie Cleanup

Webhook Setup

1. Sonarr Webhook (Required)

2. Plex Webhook (For Viewing Automation — Plex Pass required)

2b. Tautulli Webhook (Optional — Plex users who prefer Tautulli history)

3. Jellyfin Webhook (For Viewing Automation)

Mode A: Real-Time (Recommended)

Mode B: Polling

4. Emby Webhook (For Viewing Automation)

4. Jellyseerr/Overseerr Webhook (Optional)

How to Use

Create Your First Rule

Adding Series

Path 1: From outside Episeerr (Sonarr, Seerr, nzb360, etc.)

Path 2: Plex Watchlist Sync

Path 3: Search within Episeerr

Existing series: manual assignment

Episode Selection

One-time Sonarr setup (required for Path 1 and Path 2 only):

Entering the selection flow:

Selection Flow and Rule Picker

Features Explained

🔄 Plex Watchlist Sync

🎯 Episode Selection

📌 Always Have (Rule Parameter)

⚡ Viewing Automation

💾 Storage Management

Configuration Examples

Binge Watcher

Current Shows

Protected Series

Season Binger

Showcase

One-at-a-Time with Pilot

Sequential Activation (one season at a time)

Troubleshooting

Container Won't Start

Webhooks Not Working

Episodes Not Monitoring

Tags Not Working

Jellyfin Not Working

Screenshots

FAQ

Plex Watchlist Sync

General

Tags & Assignment

Viewing Automation

Deletions

Jellyfin Specific

Storage Management

Support

Get Help

Logs Location

Common Log Searches

Contributing

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Packages