epg

EPG

Tools for downloading the EPG (Electronic Program Guide) for thousands of TV channels from hundreds of sources.

Table of contents

• ✨ Installation
• 🚀 Usage
• 💫 Update
• 🐋 Docker
• 📅 Guides
• 🗄 Database
• 👨‍💻 API
• 📚 Resources
• 💬 Discussions
• 🛠 Contribution
• 📄 License

Installation

First, you need to install Node.js on your computer. You will also need to install Git to follow these instructions.

After that open the Console (or Terminal if you have macOS) and type the following command:

git clone --depth 1 -b master https://github.com/iptv-org/epg.git

This will copy all the code from the repository to your computer into the epg folder. After that, we just need to go to the folder we created:

cd epg

And install all the dependencies:

npm install

Usage

To start the download of the guide, select one of the supported sites from SITES.md file and paste its name into the command below:

npm run grab --- --sites=example.com

Then run it and wait for the guide to finish downloading. When finished, a new guide.xml file will appear in the current directory.

You can also customize the behavior of the script using this options:

Usage: npm run grab --- [options]

Options:
  -s, --sites <names>           A comma-separated list of the sites to parse
  -c, --channels <path>         Path to *.channels.xml file (required if the "--sites" attribute is
                                not specified)
  -o, --output <path>           Path to output file (default: "guide.xml")
  -l, --lang <codes>            Allows you to restrict downloading to channels in specified languages only (example: "en,id")
  -t, --timeout <milliseconds>  Timeout for each request in milliseconds (default: 30000)
  -d, --delay <milliseconds>    Delay between request in milliseconds (default: 0)
  -x, --proxy <url>             Use the specified proxy (example: "socks5://username:[email protected]:1234")
  --days <days>                 Number of days for which the program will be loaded (defaults to the value from the site config)
  --maxConnections <number>     Number of concurrent requests (default: 1)
  --gzip [path]                 Specifies whether or not to create a compressed version of the guide (default: false)
  --json [path]                 Specifies whether or not to create a JSON version of the guide (default: false)
  --curl                        Display each request as CURL (default: false)

Downloading from multiple sites at once

To do this, simply list the site names separated by commas:

npm run grab --- --sites=example1.com,example2.com

To avoid mixing guides from different sites into a single output file, we can also automatically split the output into separate files based on the site name:

npm run grab --- --sites=example1.com,example2.com --output=guides/{site}.xml

Parallel downloading

By default, the guide for each channel is downloaded one by one, but you can change this behavior by increasing the number of simultaneous requests using the --maxConnections attribute:

npm run grab --- --sites=example.com --maxConnections=10

But be aware that under heavy load some sites may start return an error or completely block your access.

Use custom channel list

Create an XML file and copy the descriptions of all the channels you need from the /sites into it:

<?xml version="1.0" encoding="UTF-8"?>
<channels>
  <channel site="arirang.com" lang="en" xmltv_id="ArirangTV.kr" site_id="CH_K">Arirang TV</channel>
  ...
</channels>

And then specify the path to that file via the --channels attribute:

npm run grab --- --channels=path/to/custom.channels.xml

Run on schedule

If you want to download guides on a schedule, you can use cron or any other task scheduler. Currently, we use a tool called chronos for this purpose.

To start it, you only need to specify the necessary grab command and cron expression:

npx chronos --execute="npm run grab --- --sites=example.com" --pattern="0 0,12 * * *" --log

For more info go to chronos documentation.

Access the guide by URL

You can make the guide available via URL by running your own server. The easiest way to do this is to run this command:

npx serve

After that, the guide will be available at the link:

http://localhost:3000/guide.xml

In addition it will be available to other devices on the same local network at the address:

http://<your_local_ip_address>:3000/guide.xml

For more info go to serve documentation.

Update

If you have downloaded the repository code according to the instructions above, then to update it will be enough to run the command:

git pull

And then update all the dependencies:

npm install

Docker

Pull an image

docker pull ghcr.io/iptv-org/epg:master

Create and run container

docker run -p 3000:3000 -v /path/to/channels.xml:/epg/public/channels.xml ghcr.io/iptv-org/epg:master

By default, the guide will be downloaded every day at 00:00 UTC and saved to the /epg/public/guide.xml file inside the container.

From the outside, it will be available at this link:

http://localhost:3000/guide.xml

or

http://<your_local_ip_address>:3000/guide.xml

Environment Variables

To fine-tune the execution, you can pass environment variables to the container as follows:

docker run \
-p 5000:3000 \
-v /path/to/channels.xml:/epg/public/channels.xml \
-e CRON_SCHEDULE="0 0,12 * * *" \
-e MAX_CONNECTIONS=10 \
-e GZIP=true \
-e JSON=true \
-e CURL=true \
-e PROXY="socks5://127.0.0.1:1234" \
-e DAYS=14 \
-e TIMEOUT=5 \
-e DELAY=2 \
-e RUN_AT_STARTUP=true \
ghcr.io/iptv-org/epg:master

Variable	Description
CRON_SCHEDULE	A cron expression describing the schedule of the guide loadings (default: "0 0 * * *")
MAX_CONNECTIONS	Limit on the number of concurrent requests (default: 1)
GZIP	Boolean value indicating whether to create a compressed version of the guide (default: false)
JSON	Boolean value indicating whether to create a JSON version of the guide (default: false)
CURL	Display each request as CURL (default: false)
PROXY	Use the specified proxy
DAYS	Number of days for which the guide will be loaded (defaults to the value from the site config)
TIMEOUT	Timeout for each request in milliseconds (default: 30000)
DELAY	Delay between request in milliseconds (default: 0)
RUN_AT_STARTUP	Run grab on container startup (default: true)

Guides

Any user can share the guides they have created with the rest of the community. A complete list of these guides and their current status can be found in the GUIDES.md file.

Database

All channel data is taken from the iptv-org/database repository. If you find any errors please open a new issue there.

API

The API documentation can be found in the iptv-org/api repository.

Resources

Links to other useful IPTV-related resources can be found in the iptv-org/awesome-iptv repository.

Discussions

If you have a question or an idea, you can post it in the Discussions tab.

Contribution

Please make sure to read the Contributing Guide before sending issue or a pull request.

And thank you to everyone who has already contributed!

Backers

Contributors

License