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
🐛 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
- 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
- Fixed ExternalClientManager to properly use TMDB_COUNTRY environment variable
- Added detailed TMDB API call logging to debug why external clients return None
- Will show available countries, release types, and specific API responses
- Should resolve the "no_valid_date_source" issue for rename-first movies
Version bumped to 0.2.17
- Updated version for enhanced TMDB API debugging
- Container rebuild needed to see new diagnostic logs
- Will help identify TMDB API key and external client issues
- Corrected debug endpoint to use global movie_processor variable
- Was incorrectly trying to access batcher.movie_processor (doesn't exist)
- Now properly tests full TMDB fallback pipeline for rename-first movies
- Fix string-based event type parsing (grabbed, downloadFolderImported, etc.)
- Filter grab events to only count actual downloads with metadata
- Fix JSON parsing errors for dict-type event data
- Enhanced chronological processing for accurate import date detection
- Validate grab events require sourceTitle or indexer info
Fixes issue where library addition events were mistaken for download grabs,
ensuring only real download timestamps are used for
sbcrumb