From 86d2cee1f9eb39a35ea1928764d77173384c0c14 Mon Sep 17 00:00:00 2001 From: SBCrumb Date: Thu, 11 Sep 2025 11:26:39 -0400 Subject: [PATCH] Complete TV webhook processing modes documentation update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📚 Comprehensive Documentation Update: • Added TV webhook processing modes section to README.md • Updated CHANGELOG.md with configurable processing feature details • Enhanced SETUP.md with TV_WEBHOOK_PROCESSING_MODE configuration • Added Step 7 testing procedures to TESTING.md for both modes 🔧 Configuration Documentation: • Targeted Mode (default): Only process episodes mentioned in webhook • Series Mode: Process entire series directory (legacy behavior) • Smart fallback logic when episode data unavailable • Clear examples and use case recommendations 📋 Testing Instructions: • Step-by-step mode switching procedures • Expected log output examples for each mode • Environment variable configuration examples • Docker restart procedures for testing ✨ User Benefits Documented: • Efficiency comparison: targeted vs series processing • File operation reduction for targeted mode • Media server notification minimization • Backward compatibility with existing setups --- CHANGELOG.md | 5 +++++ README.md | 36 ++++++++++++++++++++++++++++++++++++ SETUP.md | 3 +++ TESTING.md | 24 ++++++++++++++++++++++++ 4 files changed, 68 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f69163..9ae32b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,11 @@ All notable changes to this project will be documented in this file. - **Season Detection**: `curl -X POST "manual/scan?path=/media/TV/Series/Season 13"` - **Episode Detection**: `curl -X POST "manual/scan?path=/media/TV/Series/Season 13/episode.mkv"` - **Automatic Processing**: Detects context and processes accordingly +- **⚙️ Configurable TV Webhook Processing**: Choose between targeted or comprehensive processing + - **Targeted Mode**: `TV_WEBHOOK_PROCESSING_MODE=targeted` (default) - Only process webhook episodes + - **Series Mode**: `TV_WEBHOOK_PROCESSING_MODE=series` - Process entire series directory + - **Smart Fallback**: Automatically falls back to series mode when episode data unavailable + - **Efficiency**: Targeted mode reduces unnecessary file operations and notifications - **🔐 Secure Configuration System**: Two-file configuration with automatic API key masking - **Main `.env`**: Paths and preferences (safe to share for debugging) - **Separate `.env.secrets`**: API keys and passwords (never committed to git) diff --git a/README.md b/README.md index 080f071..b4f9c29 100644 --- a/README.md +++ b/README.md @@ -521,6 +521,42 @@ NFOGuard now creates **full-featured NFO files** with rich metadata from Sonarr: - ✅ **Runtime** and **ratings** data - ✅ **Timestamps** showing when NFOGuard processed the file - ✅ **Smart URL-safe endpoints** for processing individual seasons/episodes +- ✅ **Configurable processing modes** for webhook efficiency + +## ⚙️ TV Webhook Processing Modes (v0.6.0+) + +NFOGuard offers two processing modes for TV show webhooks: + +### **Targeted Mode** (Default - `targeted`) +**Best for**: Efficient processing, minimal file operations +```bash +TV_WEBHOOK_PROCESSING_MODE=targeted +``` +**Behavior**: Only processes episodes mentioned in the webhook +- ✅ **1 episode downloaded** → **1 episode processed** +- ✅ **Minimal file operations** - only touches new episode +- ✅ **Reduced notifications** to media servers +- ✅ **Faster processing** for single episode downloads + +**Example**: Download S41E07 → Only S41E07.nfo gets updated + +### **Series Mode** (`series`) +**Best for**: Comprehensive updates, database synchronization +```bash +TV_WEBHOOK_PROCESSING_MODE=series +``` +**Behavior**: Processes entire TV series directory +- 📺 **1 episode downloaded** → **All series episodes processed** +- 🔄 **Complete sync** - ensures all episodes stay current +- 📋 **Database consistency** - all episode dates updated +- 🛠️ **Legacy behavior** - matches previous versions + +**Example**: Download S41E07 → All 7 episodes in season get updated + +### **Smart Fallback** +- If webhook contains no episode data → automatically uses series mode +- If targeted mode fails → falls back to series processing +- Configuration validated at startup with helpful error messages 🔍 Logging & Debugging # Enable verbose logging diff --git a/SETUP.md b/SETUP.md index 4785d04..c634feb 100644 --- a/SETUP.md +++ b/SETUP.md @@ -36,6 +36,9 @@ RADARR_DB_USER=radarr PREFER_RELEASE_DATES_OVER_FILE_DATES=true ALLOW_FILE_DATE_FALLBACK=false RELEASE_DATE_PRIORITY=digital,physical,theatrical + +# TV webhook processing mode (v0.6.0+) +TV_WEBHOOK_PROCESSING_MODE=targeted ``` ### Step 3: Configure Secrets diff --git a/TESTING.md b/TESTING.md index e569a4e..603b1bd 100644 --- a/TESTING.md +++ b/TESTING.md @@ -140,6 +140,30 @@ curl -X POST "http://localhost:8080/tv/scan-episode" \ # Verify enhanced NFO was created with metadata find /media/TV/tv -name "S01E*.nfo" | head -1 | xargs cat # Should show: , <plot>, <rating>, <runtime>, timestamps + +# Test TV webhook processing modes +export TV_WEBHOOK_PROCESSING_MODE=targeted # or series +# Download episode in Sonarr and check logs for processing mode +``` + +### Step 7: Test TV Webhook Processing Modes (v0.6.0+) +```bash +# Test targeted mode (default - processes only webhook episodes) +echo "TV_WEBHOOK_PROCESSING_MODE=targeted" >> .env +docker restart nfoguard + +# Download single episode in Sonarr, check logs should show: +# "Using targeted episode processing for 1 episodes" +# "Completed targeted processing: 1/1 episodes processed" + +# Test series mode (processes entire series) +echo "TV_WEBHOOK_PROCESSING_MODE=series" >> .env +docker restart nfoguard + +# Download single episode in Sonarr, check logs should show: +# "Using series processing mode (fallback or configured)" +# "Processing TV series: Show Name" +# "Found X episodes on disk" ``` ## 🛠 Why These Tests Are Needed