Download TV Guide

Download TV guide metadata for Jellyfin, or any other media software that accepts the XMLTV format.

Tip

tl;dr

export ZAP2IT_PASSWORD='hunter2'
./dl-guide.sh -u 'someone@example.com' -o '.'

Index

1. Installation
   1. bpkg
   2. Manual
2. Usage
   1. Password
   2. Jellyfin
   3. cron
3. Development
   1. Lint
   2. CI
4. See Also

Installation

This tool runs the zap2xml docker container, so you will need the docker engine installed on your system to use it.

Note

If you are on macOS or BSD, you will need to default to GNU tools in your environment. You can check this by running grep --version, which will tell you whether it is BSD or GNU grep.

bpkg

This is the recommended installation method. Install bpkg if you have not already.

Install the echo-eval dependency.

sudo bpkg install -g kj4ezj/ee

Then, install this tool using bpkg.

sudo bpkg install kj4ezj/dl-guide

This does a global install so dl-guide should now be in your system PATH.

You can also have bpkg install a specific version.

sudo bpkg install kj4ezj/dl-guide@v0.1.0

Manual

Install bpkg if you have not already. Clone this repo locally with git using your preferred method. Install project dependencies.

bpkg install

You can invoke the script directly from your copy of the repo.

Usage

You need a zap2it account setup with your rough location and provider to use this script. What you see while logged into the online TV guide is what this script will download.

You can provide inputs to dl-guide as arguments...

$ dl-guide [OPTIONS]

[OPTIONS] - command-line arguments to change behavior
    -c, --chown, --owner, --change-owner <USER>
        Change the ownership of the output file to the specified user. If not
        specified, the ownership will not be changed.
            Requires script be run with "sudo -E" or root privileges.

    -h, --help, -?
        Print this help message and exit.

    -l, --license
        Print software license and exit.

    -o, --output, --output-dir, --output-file, --path <PATH>
        Specify the output directory or file. If a directory is given, the
        default file name (tv-guide.xml) will be used. If no output file,
        folder, or path is given, then the default Jellyfin metadata directory
        will be used if it exists.

    -u, --username, --zap2it-username <USERNAME>
        Specify the zap2it username.

    -v, --version
        Print the script version with debug info and exit.

...or using environment variables.

Variable	Type	Description
CHOWN_USER	String	The user to change the ownership of the output file to. Equivalent to '--chown'.
OUTPUT	String	The output directory or file. Equivalent to --output.
ZAP2IT_PASSWORD	String	The password for your zap2it account (required).
ZAP2IT_USERNAME	String	The username for your zap2it account. Equivalent to --username.

Arguments take precedence over environment variables.

Password

Your zap2it password cannot be provided as a command-line argument because it would be visible to other programs on your computer via the process list and shell history. The best option is to save it to a file somewhere...

export ZAP2IT_PASSWORD='hunter2'

...then source the file.

source ~/.secrets

If you don't care about it being in your shell history, you can export it as a variable.

export ZAP2IT_PASSWORD='hunter2'

At least this keeps it out of your process list while the script is running.

If you are using Kubernetes, you can make this variable available like you would any other secret.

Jellyfin

Jellyfin doesn't care where you put the tv-guide.xml file, but I chose to put it in my Jellyfin metadata directory.

Tip

You can find your Jellyfin metadata directory in your Jellyfin web portal > hamburger menu (three horizontal lines) > Administration > Dashboard, scroll down and you will see it under Paths. Mine was /var/lib/jellyfin/metadata.

Jellyfin also may run under its own user account (usually jellyfin), depending how you installed it, in which case you will need to pass that username to dl-guide so it can make sure the permissions are correct for Jellyfin to read the output file.

sudo -E dl-guide -u 'someone@example.com' -o /var/lib/jellyfin/metadata -c jellyfin

After that, follow their instructions to point Jellyfin to the tv-guide.xml file in /var/lib/jellyfin/metadata.

Jellyfin reads the tv-guide.xml file using a scheduled task that (at least for me) is already in there by default. You can check in the Administration Dashboard > Advanced > Scheduled Tasks > Live TV > Refresh Guide using the Jellyfin web portal.

cron

Finally, run this script at regular intervals using a cron job.

Tip

Note the following command sets dl-guide to run as root. If you don't want to run dl-guide as root then you can omit sudo, but you won't be able to use the -c flag and your user account must have permission to run docker without sudo.

Open your crontab to create the schedule.

sudo crontab -e

You will see some instructions explaining the general idea, and you can use crontab.guru for help with the syntax. You probably want to run it somewhere between 1-4 times per day because sometimes zap2it throttles itself and refuses to respond. Please give a random minute offset to prevent everyone from querying the server all at once.

For example, this will run twice per day - once at 00:47, and once at 12:47.

ZAP2IT_PASSWORD='hunter2'
47 */12 * * * /usr/local/bin/dl-guide -u 'someone@example.com' -c jellyfin -o /var/lib/jellyfin/metadata

This example captures the logs so you can see it worked, this time running once per day at 14:15 local time.

ZAP2IT_PASSWORD='hunter2'
15 14 * * * /usr/local/bin/dl-guide -u 'someone@example.com' -c jellyfin -o /var/lib/jellyfin/metadata > /var/lib/jellyfin/metadata/dl-guide.log 2>&1

One more example running at 2:23, 3:23, and 4:23 AM local time.

ZAP2IT_PASSWORD='hunter2'
23 2-4/1 * * * /usr/local/bin/dl-guide -u 'someone@example.com' -c jellyfin -o /var/lib/jellyfin/metadata > /var/lib/jellyfin/metadata/dl-guide.log 2>&1

The cron syntax is the same if you choose to use a Kubernetes cron job.

Development

Contributors need these tools installed.

• act
  • docker
• bpkg
  • git
  • make
• git

Pull requests are welcomed to add support for other media software. Please sign your commits.

Lint

This project uses bashate and shellcheck for linting.

bpkg run lint

This invokes lint.sh which contains the specific configuration for each permutation of linter and target file.

CI

This repo uses GitHub Actions workflows for CI.

1. dl-guide CI - initialize and lint the dl-guide 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.

bpkg run act

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

See Also

• crontab.guru
• echo-eval
• Jellyfin
  • Documentation
    • Adding Guide Data
  • GitHub
  • Website
• zap2it
• zap2xml
  • Docker Hub
  • GitHub

---

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.