📦 PyPI Status: Now available on PyPI! Install with
pip install gracenote2epg[full]
A modern Python implementation for downloading TV guide data from tvlistings.gracenote.com with intelligent caching and TVheadend integration.
- XMLTV Standard Compliant - Full DTD compliance for maximum compatibility
- Intelligent Caching - 95%+ cache efficiency with smart refresh strategies
- Multi-language Support - Automatic French/English/Spanish detection and translations
- TVheadend Integration - Seamless channel filtering and matching
- Unified Cache Management - Streamlined configuration for all retention policies
- Platform Agnostic - Auto-detection for Raspberry Pi, Synology NAS, and Linux
# Recommended: Install with all features
pip install gracenote2epg[full]
# Basic installation (core features only)
pip install gracenote2epg
# Alternative: Install from GitHub
pip install "gracenote2epg[full] @ git+https://github.com/th0ma7/[email protected]"# Install from GitHub (latest)
pip install "gracenote2epg[dev] @ git+https://github.com/th0ma7/gracenote2epg.git"
# Clone and install for development
git clone https://github.com/th0ma7/gracenote2epg.git
cd gracenote2epg
pip install -e .[dev]- Python: 3.7 or higher
- Required:
requests>=2.25.0 - Optional:
langdetect>=1.0.9(language detection),polib>=1.1.0(translations)
# Show capabilities (XMLTV standard)
tv_grab_gracenote2epg --capabilities
# Download 7 days of guide data
tv_grab_gracenote2epg --days 7 --zip 92101
# Test lineup detection
tv_grab_gracenote2epg --show-lineup --zip 92101
# Canadian postal code with console output
tv_grab_gracenote2epg --days 3 --postal J3B1M4 --console
# Save to custom file with debug info
tv_grab_gracenote2epg --days 7 --zip 92101 --output guide.xml --debug
# Use specific lineup (auto-extracts location)
tv_grab_gracenote2epg --days 7 --lineupid CAN-OTAJ3B1M4
# Disable language detection
tv_grab_gracenote2epg --days 7 --zip 92101 --langdetect false💡 TVheadend Users - Easy Setup: Most users don't need to edit configuration files! Simply use TVheadend's Extra arguments box to add your parameters like
--days 7 --zip 92101 --langdetect false(Configuration → Channel/EPG → EPG Grabber Modules). See TVheadend Integration Guide for details.
# In TVheadend Extra arguments box:
--days 7 --zip 92101
--days 14 --postal J3B1M4 --langdetect false
--days 7 --zip 90210 --lineupid autoImportant: Extra arguments override the default configuration file, so you typically don't need to edit
conf/gracenote2epg.xmlmanually.
Also note that the gracenote2epg auto-creates a configuration file on first run. You can then modify as needed:
<?xml version="1.0" encoding="utf-8"?>
<settings version="5">
<setting id="zipcode">92101</setting> <!-- Your ZIP/postal code -->
<setting id="lineupid">auto</setting> <!-- Auto-detect lineup -->
<setting id="days">7</setting> <!-- Guide duration -->
</settings>- Installation Guide - Installation instructions and software migration
- Configuration - Complete configuration reference
- Lineup Configuration - Finding and configuring your TV lineup
- TVheadend Integration - TVheadend setup, EPG migration, and troubleshooting
- Troubleshooting - General issues and solutions
- Development Roadmap - Feature roadmap, upcoming versions, and planned enhancements
- Contributing Guide - Contributing, testing, XMLTV validation, and development setup
- Cache & Retention Policies - Managing cache and log retention
- Log Rotation - Built-in log rotation system
- Development Scripts - Utility scripts for testing and distribution
- Check the troubleshooting guide
- Test your lineup:
tv_grab_gracenote2epg --show-lineup --zip YOUR_CODE - Enable debug logging:
tv_grab_gracenote2epg --debug --console - Create an issue with logs
GPL v3 - Same as original script.module.zap2epg project
Based on edit4ever's script.module.zap2epg with enhancements and modern Python architecture.