GraceNote XMLTV Scraper

Generate XMLTV guide data from GraceNote/TMS listings for use with Jellyfin, Plex, Emby, TVHeadend, and other DVR/IPTV software.

Features

• Scrapes 14 days of GraceNote/TMS program listings and outputs standard XMLTV format
• Enriches programs with TMDB poster images, ratings, descriptions, and release dates
• Enriches channel icons via the tv-logo/tv-logos project
• Runs as a long-lived server with automatic 24-hour refresh, or as a one-shot scrape for cron jobs
• Guide data cached on disk — fast restarts without re-scraping
• Automatic XMLTV file rotation with 7-day retention
• Bonus: built-in retro TV guide web UI ("The Grid")

Jellyfin / Plex Setup

1. Run the scraper in server mode (see below)
2. In your DVR software, add an XMLTV guide source pointing to:

   http://<your-host>:8080/xmlguide.xmltv
   

3. Guide data refreshes automatically every 24 hours

Alternatively, use --guide-only mode with a cron job and point your DVR software at the local xmlguide.xmltv file.

Quick Start (Docker Compose)

1. Clone the repo:

   git clone https://github.com/daniel-widrick/GraceNoteScraper.git
   cd GraceNoteScraper

2. Copy and fill in the environment file:

   cp .env.example .env
   # Edit .env with your headend/lineup details and optional TMDB token

3. Start the container:

   docker compose up -d

4. Point your DVR software at http://<your-host>:8080/xmlguide.xmltv

Guide data, caches, and images are persisted in a Docker volume. The container restarts automatically and refreshes guide data every 24 hours.

To view logs:

docker compose logs -f

To rebuild after pulling updates:

docker compose up -d --build

Requirements

• Docker and Docker Compose, or Go 1.25+ for building from source
• A GraceNote/TMS headend lineup ID
• (Optional) A TMDB API read access token for poster images and metadata

Building from Source

If you prefer to run without Docker:

go build -o gracenotescraper .
cp .env.example .env
# Edit .env
./gracenotescraper

Scrape-only mode

Scrapes once, writes xmlguide.xmltv to the working directory, and exits. Useful for cron-based setups where you don't need the server running.

./gracenotescraper --guide-only

Environment Variables

Variable	Description	Default
GN_HEADEND	GraceNote headend/lineup ID	—
GN_LINEUP	Full lineup string	—
GN_COUNTRY	Country code	USA
GN_ZIPCODE	ZIP code for lineup	—
GN_LANGUAGE	Language code	en
GN_DEVICE	Device identifier	-
TMDB_TOKEN	TMDB read access token (optional)	—
BASE_URL	Server base URL — rewrites XMLTV image URLs to use the built-in proxy cache (e.g. http://192.168.1.50:8080)	—
PORT	HTTP server port	8080

HTTP Endpoints

Endpoint	Description
GET /xmlguide.xmltv	XMLTV guide data (point your DVR here)
GET /api/guide.json	Guide data as JSON
GET /	The Grid — built-in web UI
GET /img?url=...	Image proxy with local cache

The Grid

The server includes a built-in retro-styled TV guide web UI at the root URL. It auto-scrolls through your channel lineup and shows program details, posters, and metadata. Handy for a quick glance at what's on without opening your DVR app.

Project Structure

main.go          Entry point, HTTP server, scraper, image proxy
guide/           GraceNote data types and XMLTV conversion
web/             HTTP client for GraceNote API
tmdb/            TMDB client and cache
tvlogo/          TV logo resolver and cache
util/            Shared helpers
index.html       The Grid web UI (embedded at build time)
guide.tmpl       XMLTV output template (embedded at build time)

---

_{Portions of this project were developed with the assistance of generative AI (Claude).}