- Add prefixed batch keys (movie:imdbid, tv:imdbid) to prevent IMDb ID collisions
- Add path existence validation for Radarr webhooks to reject invalid mappings early
- Remove duplicate Radarr webhook handler code
- Add debug scripts for troubleshooting webhook and path mapping issues
- Create corrected .env template with fixed TV_PATHS and SONARR_ROOT_FOLDERS
This fixes the issue where TV path mapping failures caused movie webhooks
to process wrong movies due to shared batch queue corruption.
Documentation Enhancement:
- Add missing TVDB_API_KEY to all relevant sections in README.md
- Create comprehensive API keys reference table with purposes and sources
- Add centralized API Keys Configuration section with clear examples
- Document how to resolve "TVDB API key not configured" warnings
- Include direct links to obtain API keys from each service
API Keys Covered:
- TMDB_API_KEY - Movie release dates and metadata fallbacks
- TVDB_API_KEY - TV show metadata and Emby compatibility (was missing!)
- RADARR_API_KEY - Movie import history and database access
- SONARR_API_KEY - TV episode import history
This resolves user questions about the TVDB API key warning and provides
complete documentation for all external API integrations.
NFO Organization Enhancement:
- Move all NFOGuard elements (dateadded, lockdata, comments) to bottom of NFO files
- Remove existing NFOGuard elements and re-add at bottom for clean organization
- Provides better separation between media metadata and NFOGuard management
- Easier to read NFO files when Radarr/Sonarr has already populated extensive metadata
Before: NFOGuard elements mixed throughout existing metadata
After: All media metadata first, then NFOGuard elements grouped at bottom
This addresses user feedback about NFO readability when files already contain
extensive metadata from Radarr, making it easier to see both media info and
NFOGuard management details in a logical order.
Revolutionary Workflow Changes (v0.7.0):
This fundamentally changes how NFOGuard handles timestamps and processing priority.
Webhooks = Source of Truth:
- First webhook fires → Use current timestamp → Store as permanent database entry
- Subsequent webhooks (upgrades) → Check database → Use original first-seen timestamp
- No more API calls during webhook processing → Webhook timing is ultimate authority
- Movies and TV episodes both use webhook-first approach
Manual Scans = Smart Fallback Logic:
- Priority 1: Our database (webhook timestamps) - database always wins
- Priority 2: Sonarr/Radarr import history (first import only)
- Priority 3: Air date as dateadded (final fallback)
Technical Implementation:
- Enhanced _get_webhook_episode_date() to use current timestamp as source of truth
- Added webhook_mode parameter to process_movie() for separate webhook logic
- All manual scans prioritize database entries before making API calls
- All timestamps converted to container timezone (Eastern Time)
- Enhanced debug logging for database lookups and timestamp decisions
Expected Workflow:
First download at 8:30am → webhook timestamp stored in database
Upgrade at 2:00pm → database entry found → original 8:30am timestamp preserved
Manual scan → database entry found → 8:30am timestamp used
This ensures the first-seen webhook timestamp is the permanent source of truth,
with upgrades and manual scans always preserving the original download time.
Critical Fix for Episode Import Dates:
- Webhook episodes now query Sonarr import history instead of using current time
- Fix _get_webhook_episode_date() to follow same logic as manual scans
- Convert import dates from UTC to local timezone for NFO dateadded fields
- Episodes now show 'sonarr:history.import' source instead of 'webhook:new_download'
Before: <dateadded>2025-09-14T12:40:07+00:00</dateadded> (current webhook time)
After: <dateadded>2025-09-14T08:40:07-04:00</dateadded> (real import time in local timezone)
This fixes the issue where episodes downloaded at 8:40am EST were showing
12:40pm UTC webhook time instead of the actual import timestamp.
Enhanced webhook processing now:
1. Checks database for existing entries (prevents duplicates)
2. Queries Sonarr import history for real import dates
3. Converts UTC import dates to local timezone
4. Only uses current time as last resort for true new downloads
NFO Management Timestamp Fix:
- Fix NFO management comments to use local timezone instead of UTC
- Both movie and TV episode NFO files now show consistent local timezone
- Comments now show: <!-- managed by NFOGuard at 2025-09-14T09:29:06-04:00 -->
Enhanced Episode Processing Debug:
- Add comprehensive debug logging for webhook episode database lookups
- Track IMDb ID and season/episode info throughout processing pipeline
- Add database write verification to catch storage issues immediately
- Enhanced logging will help identify duplicate processing root causes
This addresses the issue where episodes were being treated as new downloads
instead of finding existing database entries, helping prevent duplicate processing.
- Fix NFO dateadded timestamps to use local timezone instead of UTC
- Convert Radarr/Sonarr import dates from UTC to local timezone for NFO files
- Update webhook episode processing to use local time for new downloads
- Convert file modification time fallbacks to local timezone
- Preserve historical dates (aired, premiered) in original UTC format
- Replace all placeholder logging functions with centralized timezone-aware logging
- Add convert_utc_to_local() utility function for timestamp conversion
- Now all logs AND NFO files show consistent local timezone formatting
Users with TZ=America/New_York will now see:
- Logs: [2025-09-14T09:37:00-04:00]
- NFO files: <dateadded>2025-09-14T09:37:00-04:00</dateadded>
- Update VERSION file from 0.6.1 to 0.6.4 to match timezone logging release
- Add development workflow instructions to SUMMARY.md for future updates
- Document Claude Code's authority to write commits and push changes
- Establish version consistency requirements across VERSION, SUMMARY.md, and git tags
- Fix inconsistent timestamp formats in logs for easier troubleshooting
- All logging systems now respect Docker TZ environment variable (e.g., TZ=America/New_York)
- Add TimezoneAwareFormatter for Python's standard logging module
- Enhance _log function with robust timezone support and fallbacks
- Replace placeholder logging functions with centralized core.logging._log
- Support both zoneinfo (Python 3.9+) and pytz (older versions)
- Users now see consistent timezone formatting across all log outputs
💾 Smart NFO File Management:
- Add intelligent content comparison to prevent unnecessary file overwrites
- Only update NFO files when content actually changes (ignoring timestamp differences)
- Dramatically reduce file system writes and improve scan performance
- Applied to both TV episodes and movies for comprehensive efficiency
- New _nfo_content_matches() method for smart content comparison
🗓️ Fix Episode Date Field Mapping:
- BREAKING: Correct date field usage in episode NFOs
- <aired> and <premiered>: Now use historical air dates (e.g., 1951-10-15)
- <dateadded>: Correctly shows actual download/import date (e.g., 2025-09-13)
- Resolves confusion between when show aired vs when user downloaded it
- Media servers now show historically accurate metadata with working "Recently Added"
🎯 Technical Changes:
- Enhanced create_episode_nfo() with content comparison logic
- Enhanced create_movie_nfo() with content comparison logic
- Separated historical date logic from import date logic
- Added comprehensive debug logging for file skip/update decisions
🏆 User Experience:
- Faster scans with fewer unnecessary file operations
- Correct historical context in media servers
- "Recently Added" functionality preserved and working
- No more metadata confusion between air dates and import dates
Example NFO output:
- <aired>1951-10-15</aired> (historical)
- <dateadded>2025-09-13T21:39:28+00:00</dateadded> (when downloaded)
- <premiered>1951-10-15</premiered> (historical)
🎯 Problem Fixed:
- TV episodes downloaded today showed historical air dates (1951) as dateadded
- Episodes appeared as old content instead of "recently added" in media servers
- Incorrect fallback logic used air dates instead of actual download times
⚡ Revolutionary Changes:
- Webhook-first processing: When Sonarr webhook fires → use current timestamp
- Database priority: Existing NFOguard entries preserved (no re-processing)
- Smart backfill: Manual scans check Sonarr import history first
- Clear separation: Webhook vs backfill use different logic paths
🔧 Technical Implementation:
- New method: _get_webhook_episode_date() for webhook-specific handling
- Enhanced method: _get_single_episode_date() for proper backfill priority
- Database-first approach: Always check NFOguard DB before external APIs
📋 Correct Processing Flow:
1. New episode download → Sonarr webhook → current time as dateadded
2. Re-download same episode → use existing stored date (preserve original)
3. Backfill scan → NFOguard DB → Sonarr history → air dates (last resort)
4. No bulk import - database populated through webhooks and manual scans
🏆 Results:
- Episodes downloaded today now show today's date as dateadded
- Historical air dates preserved in aired field for accuracy
- "Recently Added" functionality restored in media servers
- No regression for existing properly-dated episodes
🐛 Bug Fixes:
- Fixed f-string syntax error in core/nfo_manager.py:324
- Resolved backslash escaping issue preventing startup
- Issue: Emby displays DateCreated field which gets updated on metadata refresh
- Root cause: Emby ignores <dateadded> but reads <aired> for TV episodes
- Solution: Write import date to <aired> field instead of actual air date
- Emby will now display import date (Feb 19) instead of scan date (Sep 11)
- Maintains backward compatibility with fallback to actual air date
🔧 Pipeline Fix:
• Added error handling for docker history command that was failing
• Exit status 141 (SIGPIPE) from head command causing pipeline failure
• Build was actually successful, just diagnostic command failing
✅ Changes:
• Wrapped docker history in proper error handling
• Pipeline will continue even if history display fails
• Build success is preserved regardless of diagnostic command issues
🎯 Root Cause:
• Permission issue with Docker config file loading
• SIGPIPE when head command terminates docker history output
• Non-critical diagnostic causing critical failure
📚 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
⚙️ New Configuration Option:
• Added TV_WEBHOOK_PROCESSING_MODE environment variable
• targeted = Only process episodes mentioned in webhook (efficient, default)
• series = Process entire series directory (comprehensive, previous behavior)
🎯 Targeted Episode Processing:
• New process_webhook_episodes() method for precise processing
• Only updates NFOs for downloaded episodes (e.g., just S41E07)
• Reduces unnecessary file operations and Emby notifications
• Falls back to series processing if no episode data in webhook
🔧 Implementation Details:
• Modified Sonarr webhook handler to pass episode data
• Enhanced batch processor with mode detection
• Maintains backward compatibility with existing behavior
• Added comprehensive logging for processing mode selection
✨ Benefits:
• Efficient: 1 download = 1 episode processed (not entire series)
• Configurable: Users can choose preferred behavior via .env
• Compatible: Works with existing autoscan/Emby refresh systems
• Smart: Falls back gracefully when episode data unavailable
📚 Documentation Updates:
• Updated CHANGELOG.md with comprehensive v0.6.0 feature list
• Enhanced README.md with new TV processing endpoints and examples
• Updated SETUP.md with required Sonarr API key configuration
• Enhanced TESTING.md with v0.6.0 TV testing procedures
• Updated .env templates with proper Sonarr requirements
🔧 Configuration Updates:
• Mark SONARR_API_KEY as REQUIRED for v0.6.0+ Enhanced TV NFOs
• Updated version examples from 0.5.1 to 0.6.0
• Added JSON response examples for new TV endpoints
• Clarified URL-safe vs URL-encoded endpoint options
📋 Complete File Review:
• Verified all Python imports are consistent across modules
• Confirmed all typing imports (Dict, Any, List, Optional) are present
• Validated configuration templates match actual requirements
• Added comprehensive testing procedures for TV enhancements
✅ Ready for Production:
• All endpoints documented with examples
• Configuration requirements clearly specified
• Testing procedures comprehensive for troubleshooting
• Backward compatibility maintained throughout
🐛 Database Fix:
• Add missing get_episode_date() method to NFOGuardDatabase
• Fixes: 'NFOGuardDatabase' object has no attribute 'get_episode_date'
🔄 Version Update:
• Bump VERSION from 0.2.22 to 0.6.0
• Major feature release with comprehensive TV enhancements
✅ Now Works:
• Single season processing via /tv/scan-season
• Single episode processing via /tv/scan-episode
• Enhanced NFO generation with Sonarr API metadata
• Database queries for existing episode dates
✨ Features Added:
• Single season/episode processing capability via new endpoints
• Enhanced NFO generation with full Sonarr API metadata (titles, plots, ratings)
• NFOGuard timestamp tracking in all NFO source comments
• URL-safe /tv/scan-season and /tv/scan-episode endpoints
🔧 Technical Improvements:
• Fixed URL encoding issues for paths with spaces and special characters
• Enhanced TVProcessor with process_season() and process_episode_file() methods
• Rich metadata extraction from Sonarr API (episode titles, plots, runtime, ratings)
• XML escaping for special characters in metadata
• Comprehensive episode parsing (SxxExx and numeric formats)
📚 Documentation:
• Updated README with new TV processing endpoints
• Added enhanced NFO generation examples showing before/after
• Documented URL-safe alternatives to manual scan paths
🎯 User Benefits:
• Can now process single seasons: Chicago Fire Season 13
• Can now process single episodes: S13E21 files
• Enhanced NFO files with full episode metadata for better Emby/Plex experience
• Timestamps show when NFOGuard processed each file
- Added TMDB_TYPE_PRIORITY environment variable for user-configurable release type preferences
- Default priority: 4,5,3,2,6,1 (Digital → Physical → Theatrical → Limited → TV → Premiere)
- Replaces random first-available selection with intelligent priority-based selection
- Enhanced logging shows selected type and full priority order
- Users can customize priority based on their preferences (e.g. theatrical first)
Version bumped to 0.2.22
- Added detailed explanation of 4-tier fallback hierarchy
- Documents all TMDB release types (1-6) with clear descriptions
- Explains rename-first detection and Radarr NFO fallback logic
- Shows difference between import_then_digital vs digital_then_import priorities
- Version bumped to 0.2.21
- TMDB now accepts ANY release type (1-6+) for maximum coverage
- Added Radarr NFO <premiered> date extraction as additional fallback
- For rename-first movies: Import → Any TMDB → Radarr NFO → File dates
- Much more aggressive about using ANY reasonable date over bad file dates
- Covers edge cases where TMDB has unusual release types
Version bumped to 0.2.20
- Enhanced digital release detection to accept Type 2 (Limited theatrical) dates
- Fixes "To Catch a Killer (2023)" and similar movies that only have festival/limited releases
- Better coverage for modern movies that premiere at film festivals before wide release
- Type 2 dates are better than bad file modification dates for rename-first scenarios
Version bumped to 0.2.19
- Enhanced digital release detection to also accept Type 6 (TV premiere) dates
- Fixes issue with 1966 "How the Grinch Stole Christmas!" and similar TV specials
- Detailed debugging revealed Type 6 was available but not being used
- Now properly handles older content that premiered on TV rather than theaters
Version bumped to 0.2.18
sbcrumb
jskala