This script grabs EPG data from the ZiggoGo TV service and formats it into XMLTV format. This script is designed for use with TVHeadend, but can also be used in standalone mode.
ZiggoGo EPG optimizes grabbing on TV information by using a cache database (implemented using SQLite). By reusing this cache between runs, the amount of data downloading is severely reduced. This has 2 main advantages. First of all, grabbing is a lot faster (except for the initial run, obviously) as a lot less requests to the Ziggo server need to be made. Secondly, because a lot less request are being made to the Ziggo server, the impact of running ZiggoGo EPG on these servers will be limited.
Even though ZiggoGo EPG is optimized, it is not recommended to run this program more than twice a day. If more frequent XMLTV
generation is desired (for example, for testing purposes), use the --generate-only
flag. See the Usage section for
more details.
In this mode, TVHeadend will be asked to provide a list of known TV channels. The script will try to match these up to the ZiggoGo EPG and only grab data for these channels. Once the EPG data has been grabbed, the resulting XMLTV data is directly written to TVHeadend without creating an intermediate file.
The TVHeadend mode is the recommended mode for ZiggoGo EPG and is thus the default mode.
In this mode, the channel list will be read from an input file (recommended) or can be given per channel on the command line. The XMLTV data will then be output to the file of choice.
For convenience, ZiggoGo EPG can output all known channels to a file. This file can be edited to the users desire and then used as the input file.
Python 3.6+ is required to run this script. In addition, some external Pyton packages are used. These are listed in the
requirements.txt
file. You can easily install these packages using the following command:
pip install -r requirements.txt
For a quick overview of all available options, run:
./ziggogoepg.py --help
ZiggoGo EPG supports the following basic options:
-h
, --help
: Opens the program help and exits.-s
, --configuration
: Select the configuration to use. The default configuration is ziggo-nl
. Currently supported
configurations are (see also Adding configurations):
upc-pl
ziggo-nl
-n
, --scan-days
: Set the number of days to scan from the ZiggoGo servers. The default of 14 is the current maximum of
the servers. To reduce grabbing time, memory use and storgae requirements, this value can be lowered.-f
, --file-mode
: Runs the grabber in file mode instead of the default TVHeadend mode. See the
TVHeadend mode and Standalone mode sections for a detailed explanation.The following options are supported in TVHeadend mode:
--tvh-host
: Give the hostname of the TVHeadend server. Defaults to localhost
, which should be safe as writing the XMLTV file
can normally only be done on the local machine (unless you are using a networked file system).--tvh-port
: Give the port number of the TVHeadand server. Defaults to 9981
, which should normally work unless you configured
TVHeadend to run on a different port.--tvh-username
: The username to use for connecting to TVHeadend. This can (and should) be a user with limited access.--tvh-password
: The password to use for connecting to TVHeadend. Note that this password can be seen on the command line.--tvh-socket SOCKET
: The path to xmltv socket of TVHeadend, used to write the XMLTV data. Defaults to
/home/hts/.hts/tvheadend/epggrab/xmltv.sock
which should work for any installation that installed TVHeadend under the
recommended system user. Note that this socket file only exists if the XMLTV grabber was enabled in TVHeadend.The following options are supported in standalone file mode:
--channel-file
: Sets the filename of the file to read (or write, see --write-channel-list
) the channel list from. This can
be only a filename or a full path. Defaults to channels.txt
.-c
, --channel
: Can be used instead of the --channel-file
option to give a specific channel to grab on the command line.
The option can be repeated multiple times to specify multiple channels (but in that case, using the --channel-file
is
highly recommended).--write-channel-list
: If given the currently known channels are retrieved from the ZiggoGo servers and are output to the file
specified by the --channel-file
option. No EPG data will be grabbed and no XMLTV file will be generated. This is option is
useful when first starting with the standalone file mode as this gives a known-good channels file to start your configuration
with. It is recommended to first edit this file, removing any unwanted channels, before starting normal use of the
standalne file mode. Warning: Using this option will overwrite any existing file at the location of --channel-file
!The following options are tweaks that can be used by advanced users:
--timezone
: All start and stop (end) times in the XMLTV file have a timezone associated with them. By default
the timezone from the confifuration file is used as it is most appropriate for your EPG. And your TV software should be
able to handle this timezone without any issue. However, if you TV software has issues, you can try other timezones. You can
choose most of the timezones listed on https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, with 'UTC' being your best
bet in case of issues. Note that timezone assignment and translation is done by the pytz
library, so if this library is kept
up to date you should experience no timezone issues.--database-location
: By default the ziggoepg_cache.sqlite
file is stored in the working directory of the script. Should you
desire a different location (for example, a file system that is better suited to handle a database file), an alternative path
(but not filename) can be specified here.--generate-only
: Great for testing the export of the XMLTV data. No contact is made with the ZiggoGo servers, the XMLTV
generation is done fully from the existing ziggoepg_cache.sqlite
file. Any useful application of this mode requires ZiggoGo
EPG to have run in a normal mode at least once before. Note that this option is ignored if the --write-channel-list
option
is used. Note that the --channel-file
, -c
or changing available channels in TVHeadand has no effect on the output of this
option (these options control updating of the ziggoepg_cache.sqlite
file only).Configuration files are stored with the ZiggoGo EPG program in .yml
(YAML) files. To create a new configuration it is easiest
to copy an existing one and name it accordingly for your region. In the configuration file, you can adjust the URL's used to
grab the EPG data from and set an appropriate timezone for the resulting XMLTV file. Note that this grabber only works with
systems from Ziggo/UPC/Liberty Global and you will have to figure out the URL's yourself by observing the network traffic of
the online viewing application from your local provider.
The following configuration options are available:
urls
epg_channel_list
: The URL where the grabber can get the currently supported channel list from the online viewer. This gives
the grabber the information it needs to map TV channel names to the internal ID's used by the EPG service.epg_segment
: The URL where the grabber can get the program overview segments. Typically, these are 6-hour segments that
contain an overview of all programs broadcast during that period. The URL must have exactly one {}
entry, which is to be
placed in the location of the URL where the segment id is normally placed. A segment id looks like a datetime without any
spacing or symbols (eg. 2022-03-11, 00:00:00 becomes 20220311000000
, which is automatically generated by the grabber in
place of the {}
entry).epg_detail
: The URL where the grabber can get the program details from each individual program. The URL must have exactly
one {}
entry, which is to be placed in the location of the URL where the program id is normally placed. A program id is a
long string that is associated with the program. This value can be seen both in the segment data and from observing the URL
called by the online viewing application from your local provider.timezone
: The timezone that is used for creating program entries in the XMLTV file. This timezone must be supported by
pytz
. See the explanation of the --timezone
option for what is allowed here.After creating the configuration, place it in the ziggogo-epg application location and call ziggogoepg.py
with the
-s
/--configuration
option, where the value is the name ofthe file without the .yml
extension (for example, to use
upc-pl.yml
, you would call ziggogoepg.py
with the option -s upc-pl
).
Inspiration for the script has been taken from https://github.com/beralt/horepg. While all code is new, some operational ideas (like automatic channel matching with TvHeaded) came from this project.
Thank you Beralt for your hard work on horepg!
Also thanks to:
upc-pl
.