Schedules Direct XMLTV

A lightweight Docker service that automatically fetches TV guide data from Schedules Direct, converts it to XMLTV format, keeps it updated on a schedule, and serves the resulting XMLTV file over HTTP.

This is particularly useful for providing Schedules Direct guide data to applications such as:

• Threadfin
• Jellyfin
• Plex
• Emby
• TVHeadend
• Other applications that accept an XMLTV URL

Features

• Automatically downloads TV listings from Schedules Direct
• Converts Schedules Direct data to XMLTV
• Performs an initial guide download when the container starts
• Automatically refreshes guide data every day
• Serves tvxml.xml using nginx
• Configurable Schedules Direct lineups
• Configurable number of guide days to download
• Configurable timezone
• Persistent XMLTV data
• Docker Compose support
• Multi-architecture Docker images
  • linux/amd64
  • linux/arm64

Docker Image

The current image is:

heroeswearkapes/schedules-direct-xmltv:latest

During the migration period, the same image is also published under the legacy repository:

heroeswearkapes/schedules-direct-update-and-serve:latest

New installations should use:

heroeswearkapes/schedules-direct-xmltv

Requirements

You will need:

• Docker or Docker Compose
• A valid Schedules Direct subscription
• At least one Schedules Direct lineup configured for your account

Schedules Direct credentials are provided to the container at runtime and are not stored in the Docker image.

Quick Start

Clone the repository:

git clone https://github.com/heroeswearkapes/schedules-direct-xmltv.git
cd schedules-direct-xmltv

Create your runtime configuration:

cp .env.example .env

Edit .env:

nano .env

At minimum, configure your Schedules Direct credentials:

SCHEDULES_DIRECT_USERNAME=your_schedules_direct_username
SCHEDULES_DIRECT_PASSWORD=your_schedules_direct_password

Then start the container:

docker compose up -d

Docker Compose

The included docker-compose.yaml uses:

services:
  xmltv:
    image: heroeswearkapes/schedules-direct-xmltv:latest
    container_name: schedules-direct-xmltv

    environment:
      SD_USERNAME: ${SCHEDULES_DIRECT_USERNAME}
      SD_PASSWORD: ${SCHEDULES_DIRECT_PASSWORD}
      SD_LINEUPS: ${SD_LINEUPS:-USA-0000001-CUSTOM,USA-DITV505-X,USA-MI21464-X,USA-YOUTUBE-X}
      SD_FETCH_DAYS: ${SD_FETCH_DAYS:-2}
      TZ: ${TZ:-America/New_York}

    ports:
      - "${XMLTV_PORT:-51969}:80"

    volumes:
      - xmltv_data:/var/www/html

    restart: unless-stopped

volumes:
  xmltv_data:

Configuration

The public .env.example contains all runtime options required by Docker Compose.

Schedules Direct Username

SCHEDULES_DIRECT_USERNAME=your_schedules_direct_username

Your Schedules Direct account username.

Schedules Direct Password

SCHEDULES_DIRECT_PASSWORD=your_schedules_direct_password

Your Schedules Direct account password.

Lineups

SD_LINEUPS=USA-0000001-CUSTOM,USA-DITV505-X,USA-MI21464-X,USA-YOUTUBE-X

Lineups are provided as a comma-separated list.

For example:

SD_LINEUPS=USA-0000001-CUSTOM,USA-DITV505-X

Use lineup IDs available to your Schedules Direct account.

Guide Days

SD_FETCH_DAYS=2

Controls how many days of guide data are downloaded during each synchronization.

For example:

SD_FETCH_DAYS=7

downloads seven days of guide data.

Timezone

TZ=America/New_York

The container performs its scheduled guide refresh at midnight according to the configured timezone.

Examples:

America/New_York
America/Chicago
America/Denver
America/Los_Angeles

HTTP Port

XMLTV_PORT=51969

This controls the host port used to access the XMLTV file.

The container itself serves HTTP through nginx on port 80.

Accessing XMLTV

With the default configuration, the generated guide is available at:

http://YOUR-SERVER-IP:51969/tvxml.xml

For example:

http://192.168.1.100:51969/tvxml.xml

Use this URL as the XMLTV source in Threadfin, Jellyfin, Plex, Emby, TVHeadend, or another compatible application.

How It Works

When the container starts:

1. Runtime configuration is read from environment variables.
2. A tv_grab_zz_sdjson configuration file is generated.
3. The configured Schedules Direct lineups are added.
4. Any stale Schedules Direct cache is removed.
5. An initial XMLTV synchronization is performed.
6. Cron is started for scheduled updates.
7. nginx starts and serves the generated XMLTV data.

The initial synchronization and scheduled synchronization both use:

tv_grab_zz_sdjson

The generated XMLTV file is stored at:

/var/www/html/tvxml.xml

Scheduled Updates

The container automatically refreshes the guide every day at midnight:

00:00

The configured TZ environment variable determines which timezone is used for the scheduled refresh.

Container logs show synchronization activity.

View logs with:

docker logs -f schedules-direct-xmltv

Typical output resembles:

[SYNC] Starting Schedules Direct data fetch...
[SYNC] Fetching 2 day(s) of guide data...
[SYNC] Completed Schedules Direct data fetch.
[SYNC] XMLTV output: /var/www/html/tvxml.xml

Persistent Data

The Docker Compose configuration uses the named volume:

xmltv_data

mounted at:

/var/www/html

This stores the generated XMLTV data and Schedules Direct configuration outside the container's writable layer.

The primary generated file is:

/var/www/html/tvxml.xml

Manual Docker Example

The container can also be run without Docker Compose.

docker run -d \
  --name schedules-direct-xmltv \
  -e SD_USERNAME="your_username" \
  -e SD_PASSWORD="your_password" \
  -e SD_LINEUPS="USA-0000001-CUSTOM" \
  -e SD_FETCH_DAYS="2" \
  -e TZ="America/New_York" \
  -p 51969:80 \
  -v xmltv_data:/var/www/html \
  --restart unless-stopped \
  heroeswearkapes/schedules-direct-xmltv:latest

Then access:

http://YOUR-SERVER-IP:51969/tvxml.xml

Multi-Architecture Support

Published Docker images support:

linux/amd64
linux/arm64

This allows the same image to run on standard x86-64 Docker hosts as well as ARM64 systems such as compatible Raspberry Pi devices.

Updating

Docker Compose

docker compose pull
docker compose up -d

Docker CLI

docker pull heroeswearkapes/schedules-direct-xmltv:latest

Then recreate the container using the same environment variables, port mapping, and persistent volume.

Troubleshooting

Container exits immediately

Check the logs:

docker logs schedules-direct-xmltv

The container requires both:

SD_USERNAME
SD_PASSWORD

If either is missing, startup will fail.

XMLTV file is unavailable

Verify the container is running:

docker ps

Then check:

docker logs schedules-direct-xmltv

The initial Schedules Direct synchronization must complete before a valid tvxml.xml is available.

Incorrect or missing channels

Verify that SD_LINEUPS contains valid lineup IDs associated with your Schedules Direct account.

Multiple lineups must be separated by commas.

Change the number of guide days

Set:

SD_FETCH_DAYS=7

and recreate the container:

docker compose up -d

Security

Schedules Direct credentials are runtime configuration.

Do not commit your .env file to Git.

The included .gitignore excludes:

.env
build.env

The .env.example file contains placeholders only and is safe to commit.

Source

Project source:

https://github.com/heroeswearkapes/schedules-direct-xmltv

Inspiration and Acknowledgements

This project was inspired by the original schedules-direct-update-and-serve project created by John Corser and its contributors.

Schedules Direct XMLTV is a separate implementation created to provide a maintained, multi-architecture Docker solution with simplified configuration, Docker Compose support, and Unraid integration.

This project uses tv_grab_zz_sdjson from the XMLTV utilities to retrieve guide data from Schedules Direct.

Disclaimer

This is an independent community project.

It is not affiliated with or endorsed by Schedules Direct, XMLTV, Threadfin, Jellyfin, Plex, Emby, TVHeadend, Docker, or Unraid.

License

This project is licensed under the MIT License.

See the LICENSE file for the full license text.