- New EpisodeNFOManager class with video filename matching
- NFO files now match video filenames instead of S01E01.nfo format
- Clean TVSeriesProcessor with proper Sonarr API integration
- Proper date lookup: database -> Sonarr import history -> airdate fallback
- Updated manual scan endpoint to use new clean processor
- Removed all migration logic and nfo_migration_required sources
This is a complete rewrite of TV episode processing with focus on:
1. NFO filenames matching video files
2. Proper dateadded field population from Sonarr
3. Clean separation of concerns
4. Robust fallback logic
- Remove bogus 'nfo_migration_required' source that bypassed proper date lookup
- Ensure episodes with existing NFOs still get processed through Sonarr API
- Episodes should get proper dateadded from Sonarr import history or airdate fallback
- Version bump to 1.9.3-longnames
- Fix movie webhook to use comprehensive IMDb detection (dir, filename, movie.nfo) instead of simple string search
- Fix batch processing NameError: use path_obj instead of undefined path variable
- Version bump to 1.8.3
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix WebhookBatcher missing nfo_manager attribute that caused movie processing errors
- Move NFOGuard comment from top to bottom of episode NFOs with other NFOGuard fields
- All NFOGuard additions now grouped together at bottom for better organization
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace simple string search with find_movie_imdb_id() method
- Check directory name, filenames, and NFO file content for IMDb ID
- Handle both full IMDb IDs (tt26394837) and number formats
- Add detailed logging for detected vs expected IMDb matching
- Fix validation failures when IMDb ID is in filename/NFO but not directory name
Resolves movie webhook processing failures when directory lacks IMDb ID
but files contain proper identification.
- Add detailed debug logging to _extract_title_from_filename() method
- Log file search, regex pattern matching, and title cleanup process
- Fix Tier 2 processing to call _get_episode_metadata() for title extraction
- Add debug logging to _get_episode_metadata() to trace execution flow
- Include both .mkv and .mp4 file checking with detailed logs
This should help identify why title extraction isn't working for
recreated NFO files and provide visibility into the extraction process.
- Modify extract_nfoguard_dates_from_episode_nfo() to detect missing titles
- Add enhance_existing_episode_nfo_with_title() method to update NFOs with titles
- Enhance Tier 1 processing to check for missing titles in existing NFO files
- Extract titles from filenames and update existing NFOs that lack title elements
- Fix NFO filename case to match S01E01.nfo format
- Preserves all existing NFO content while adding missing title elements
Addresses issue where existing NFO files with NFOGuard metadata were
skipping title extraction due to Tier 1 optimization caching.
- Add _extract_title_from_filename() method to extract episode titles from video filenames
- Enhance _get_episode_metadata() to use filename fallback when Sonarr API doesn't provide titles
- Update all _get_episode_metadata() calls to pass season directory for filename extraction
- Extract titles from patterns like: Series-S01E01-Episode Title[WEBDL-1080p][AAC2.0][h264].mkv
- Preserves existing Sonarr API behavior while providing fallback for missing titles
- Fixes episodes with missing <title> elements in NFO files when Sonarr data is incomplete
Resolves issue where episodes processed via sonarr:history.import had empty NFO titles
despite clear title information being available in the video filenames.
- Create logs/failed_movies.log for movies with no_valid_date_source
- Logs movie name, IMDb ID, failure reason, and timestamp
- Helps users identify problematic movies needing manual attention
- Useful for debugging API issues and monitoring system health
- Documented in SUMMARY.md action items for troubleshooting workflow
- Add missing xml.etree.ElementTree import to nfoguard.py
- Fix _extract_dates_from_tmdb_nfo to use tolerant XML parser
- Resolves 'name ET is not defined' error in TMDB fallback processing
- For the One (2024) should now process successfully with premiered date
- Add NFO file extraction for TV episodes with dateadded detection
- Extend three-tier optimization (NFO cache, DB cache, full processing) to TV episodes
- Add TMDB ID fallback support for movies without IMDb IDs
- Implement Tier 1.5 processing for TMDB-only movies using premiered dates
- Update documentation with complete TV episode optimization details
- Add database rebuild capabilities for both movies and TV content
- Performance improvements eliminate 90%+ of processing time on warm systems
Extended the revolutionary three-tier performance system to TV episodes:
TIER 1 (Fastest): Episode NFO File Check
- Detects existing NFOGuard data in episode NFO files (dateadded + lockdata)
- Skips all database queries AND Sonarr API calls
- Perfect for database rebuilds from existing episode NFO files
TIER 2 (Fast): Episode Database Check
- Uses complete episode database entries when available
- Skips expensive Sonarr API calls for series/episode metadata
- Creates NFO from cached data only
TIER 3 (Normal): Full Episode Processing
- Only when neither NFO nor database have data
- Queries Sonarr APIs, processes dates, enhanced metadata
TV shows now benefit from same performance improvements as movies:
- Database rebuilds from existing NFO files (instant)
- Subsequent scans 90%+ faster for processed episodes
- Large TV libraries process efficiently with intelligent caching
This completes the performance optimization system across all media types.
Implemented smart caching system that dramatically reduces processing time:
TIER 1 (Fastest): NFO File Check
- If NFO already has NFOGuard dateadded + lockdata, use it directly
- Skips both database queries AND API calls
- Perfect for movies already processed by NFOGuard
TIER 2 (Fast): Database Check
- If database has complete dateadded data, use it
- Skips expensive API calls to TMDB/OMDB/Radarr
- Creates NFO from cached data
TIER 3 (Slowest): Full Processing
- Only when neither NFO nor database have data
- Queries all APIs, processes dates, saves to database
This should dramatically improve full scan performance, especially
on subsequent runs where most movies already have NFOGuard data.
Expected speedup: 90%+ reduction in processing time for warm scans.
Added comprehensive debugging for IMDb ID detection to identify issues
with directories that don't have IMDb IDs in folder names but do have
them in filenames (like Adulthood (2025) [tt26657977]).
Also added database-first optimization that skips expensive API calls
when we already have complete data in the database. This should:
- Speed up full rescans significantly
- Reduce unnecessary API calls to TMDB/OMDB/Radarr
- Keep database size appropriate by not re-querying known movies
This should resolve both the small database size issue and improve
performance for movies that already have valid dateadded entries.
Added debug logs to understand why Flow (2019) isn't calling external APIs
while Ambush (2023) works correctly. This will show:
- should_query calculation and reasoning
- _decide_movie_dates entry point and logic path
- Whether existing database data is being used incorrectly
This should help identify why digital release date lookup works for some
movies but not others with identical database states.
The system was skipping external API calls when a database entry existed
but had no useful data (dateadded: None). This caused movies to get minimal
NFO files even when digital release dates were available.
Added condition to should_query logic: also query APIs when we have an
existing database entry but no dateadded value.
This fixes the Flow (2019) issue where it should fetch digital release
dates from TMDB/OMDB but was returning "no_valid_date_source" instead.
When Radarr can't provide import/download dates, the system now properly
uses digital release dates, theatrical dates, or air dates as the dateadded
value for both NFO files and database storage.
This fixes the issue where movies would get minimal NFO content with
"no_valid_date_source" when valid release dates were available but not
being saved to the database for future use.
Key changes:
- Use release date as dateadded when import date is None but release date exists
- Ensure all found dates are saved to database for future manual scans
- Maintain proper source tracking for debugging
- Fix NFO files getting minimal content when valid dates exist
**Root Cause**: upsert_movie_dates() was UPDATE-only, not proper upsert
- Manual scans failed to save dateadded to database (NULL values)
- Webhooks found database entries but with NULL dateadded
- Fell back to current timestamp instead of using proper import dates
**Database Fix**:
- Changed core/database.py upsert_movie_dates() from UPDATE to INSERT OR REPLACE
- Now properly saves dateadded during manual scans
- Preserves existing path with COALESCE fallback
**Webhook Enhancement**:
- Added comprehensive debug logging for database lookups
- Enhanced webhook date decision logic with proper fallback chain
- Only uses current timestamp as absolute last resort
**Impact**:
- Movies: Manual scans now persist dates, webhooks find existing entries ✅
- TV Shows: Not affected - already using proper INSERT OR REPLACE ✅
- Version: 1.5.5
- 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.
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>
- 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
⚙️ 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
✨ 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
sbcrumb