zap2xml

The zap2xml Perl script is a command-line utility that extracts electronic program guide (EPG) data for over-the-air (OTA) or cable television from any one of several service providers, parses it, collates it, and saves it in a format compatible with various media center applications. For example, you can use zap2xml to download guide data from zap2it.com in XMLTV format for free for Jellyfin, instead of paying $35/yr. for Schedules Direct. This repo packs zap2xml into a lightweight docker container with its dependencies.

Tip

Quick Start

The fastest way to get started is to forget this repo and use dl-guide. It still uses zap2xml under the hood, but it provides a user-friendly interface, help, useful log output, makes sure the output file permissions are correct for your media software, and you don't have to know how to use docker.

Note

This repo is a fork of shuaiscott/zap2xml.

Their last commit was pushed April 2021 and the maintainer will not be able to access their GitHub account until 2025. The purpose of this fork is to:

1. Rebuild the container to pull in security updates since April 2021.
2. Add CICD with scheduled builds to continue to pull in security updates as they come.
3. Publish the container somewhere more reliable that Docker Hub.
4. Consolidate community bug fixes and improvements.
5. Reduce complexity.

If you are browsing forks of shuaiscott/zap2xml wondering which fork you should use and contribute to, if any, please consider this one.

Important

The v0.1.* releases maintain backwards-compatibility with shuaiscott/zap2xml and integrate pending upstream community contributions.

• v0.1.0 - equivalent to upstream in behavior and function.
• v0.1.1 - stops logging your password.
• v0.1.2 - adds automatic retry.
• v0.1.3 - adds exponential backoff.
• v0.1.4 - supports downloading guide data from multiple users.

From v0.2.0 onwards, backwards-compatibility with the upstream repo is not guaranteed.

Index

1. Usage
2. Development
   1. Lint
   2. CI
3. See Also

Usage

You will need the docker engine installed to use this project.

Pull (download) this container from the GitHub container registry.

docker pull ghcr.io/kj4ezj/zap2xml

This container is also available on Docker Hub.

docker pull docker.io/kj4ezj/zap2xml

Download guide data to a file called tv-guide.xml in the current folder.

docker run -v "$(pwd):/data" kj4ezj/zap2xml /bin/sh -c "/zap2xml.pl -u '$ZAP2IT_USERNAME' -p '$ZAP2IT_PASSWORD' -U -o /data/tv-guide.xml"

The upstream repo provided a script that wraps zap2xml and runs it every 12 hours. You can run it in the foreground...

docker run -v "$(pwd):/data" -e "USERNAME=$ZAP2IT_USERNAME" -e "PASSWORD=$ZAP2IT_PASSWORD" -e XMLTV_FILENAME=tv-guide.xml kj4ezj/zap2xml

...or the background.

docker run -d -v "$(pwd):/data" -e "USERNAME=$ZAP2IT_USERNAME" -e "PASSWORD=$ZAP2IT_PASSWORD" -e XMLTV_FILENAME=tv-guide.xml kj4ezj/zap2xml

The wrapper loops forever, so you will need to manually kill the container. This command kills the last container you started.

docker kill "$(docker ps | tail -1 | awk '{print $1}')"

For this reason and others, the wrapper will be removed in a subsequent version. If you plan to rely upon it, please pull your container by git tag.

To prevent your password from ending up in a bunch of logs (or worse), zap2xml no longer prints the arguments it sees when it starts by default. If you need this for debugging, set:

docker run -v "$(pwd):/data" -e 'DEBUG=true' kj4ezj/zap2xml /bin/sh -c "/zap2xml.pl -u '$ZAP2IT_USERNAME' -p '$ZAP2IT_PASSWORD' -U -o /data/tv-guide.xml"

It always prints the argc so you can tell if it is seeing the correct number of arguments without exposing your password.

Development

Contributors need these tools installed.

• act
• docker
• git

Please sign your commits.

Lint

This project uses bashate and shellcheck to lint BASH scripts.

.github/workflows/lint.sh

This script contains the specific configuration for each permutation of linter and target file.

The dockerfile is not yet linted.

CI

This repo uses GitHub Actions for CI.

1. zap2xml CI - build and push the zap2xml project.
   • Pipeline
   • Documentation

The CI must pass before a pull request will be peer-reviewed.

You can run the GitHub Actions workflow(s) locally using act.

act --artifact-server-path .github/artifacts

This skips the docker tag and docker push steps because those should never be run locally.

Important

Please make sure any pipeline changes do not break act compatibility.

See Also

This list is not exhaustive, there may be other compatible consumers and providers.

• Consumers
  • Channels
  • Jellyfin
    • Adding Guide Data
  • NextPVR
  • Plex
• Providers
  • tvguide.com
  • zap2it.com
• Wrappers
  • dl-guide - user-friendly interface wrapping this container with ancillary functionality.
• XMLTV Project
  • GitHub
  • Homepage
  • XMLTV Format - documentation on the XMLTV file format.
• zap2xml
  • Docker Hub
  • GitHub Container Registry
  • shuaiscott/zap2xml - upstream repo.

---

Legal Notice
This repo contains assets created in collaboration with a large language model, machine learning algorithm, or weak artificial intelligence (AI). This notice is required in some countries.