gracenote2epg - TV Guide Grabber for North America

📦 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.

🌟 Key Features

🆕 = new in 2.0

• 📺 XMLTV standard - full DTD compliance for broad player/PVR compatibility
• ⚡ Adaptive parallel downloads 🆕 - self-tuning concurrency that rides the server's rate-limit wall
• 🎬 Rich metadata 🆕 - cast & crew credits, box-art icons, typed images, per-episode synopsis
• 🌍 Built-in geocoding 🆕 - postal/ZIP → lineup, no pandas/numpy
• 🧠 Intelligent caching - 95%+ reuse, organized into guide/, series/, movies/
• 🗣️ Multi-language - French/English/Spanish detection and translations
• 📡 TVheadend integration - channel filtering and matching
• ♻️ Unified retention - guide cache, logs, XMLTV and config backups
• 🧩 Platform agnostic - Raspberry Pi, Synology NAS, and Linux

🚀 Installation

# 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/gracenote2epg.git@v2.0.0"

📦 Development Installation

# 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]

📋 System Requirements

• Python: 3.8 or higher
• Required: requests>=2.25.0
• Optional: langdetect>=1.0.9 (language detection), polib>=1.1.0 (translations)

🛠️ Quick Examples

Command Line Examples

# 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

Configuration

💡 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.

TVheadend Integration Examples

# In TVheadend Extra arguments box:
--days 7 --zip 92101
--days 14 --postal J3B1M4 --langdetect false  
--days 7 --zip 90210 --lineupid auto

Important: Extra arguments override the default configuration file, so you typically don't need to edit conf/gracenote2epg.xml manually.

Option 2: Edit Configuration File (Advanced Users)

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>

📚 Documentation

• 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

• Development Roadmap - Feature roadmap, upcoming versions, and planned enhancements
• Contributing Guide - Contributing, testing, XMLTV validation, and development setup

Advanced Topics

• Cache & Retention Policies - Managing cache and log retention
• Log Rotation - Built-in log rotation system
• Development Scripts - Utility scripts for testing and distribution

🆘 Need Help?

1. Check the troubleshooting guide
2. Test your lineup: tv_grab_gracenote2epg --show-lineup --zip YOUR_CODE
3. Enable debug logging: tv_grab_gracenote2epg --debug --console
4. Create an issue with logs

📄 License

GPL v3 - Same as original script.module.zap2epg project

🙏 Credits

Based on edit4ever's script.module.zap2epg with enhancements and modern Python architecture.

---

View Changelog | Report Issues | Contribute