search

XMLTV / xmltv

Utilities to obtain, generate, and post-process TV listings data in XMLTV format
GNU General Public License v2.0
300 stars 94 forks source link
listings perl radio tv

readme

XMLTV 1.3.0

Table of Contents

Description

The XMLTV project provides a suite of software to gather television listings, process listings data, and help organize your TV viewing.

XMLTV listings use a mature XML file format for storing TV listings, which is defined and documented in the XMLTV DTD.

In addition to the many "grabbers" that provide listings for large parts of the world, there are also several tools to process and filter these listings.

Please see our QuickStart documentation for details on what each program does.

Changes

To see what has changed in the current XMLTV release please check the Changes file.

Installation (Package)

Linux

XMLTV is packaged for most major Linux distributions and FreeBSD. It is recommended that users install XMLTV using their preferred package manager.

Packaging status

Debian/Ubuntu

% sudo apt install xmltv

Fedora/CentOS Stream/Rocky Linux (via RPM Fusion)

% dnf install xmltv

Windows

Windows users are strongly advised to use the pre-built binary as installing all prerequisites is non-trivial. Please also check the Github release page for a pre-built release binary.

For those who want to give it a go, please read the EXE build instructions. The instructions can be used for both building xmltv.exe as well as a local install.

MacOS

XMLTV is packaged for MacOS in the MacPorts Project

Installation (Source)

Getting Source Code

Tarball/Zipfile

The source code for the current release can be downloaded as a tarball (or zipfile) from GitHub and extracted to a preferred location.

Git

The source code for all previous, current and future releases is available in our GitHub repository:

% git clone https://github.com/XMLTV/xmltv.git

Building

To build from source please ensure all required modules are available (see below). Change to the directory containing the XMLTV source:

% perl Makefile.PL
% make
% make test
% make install

To install to a custom directory, update the first line to provide a suitable PREFIX location:

% perl Makefile.PL PREFIX=/opt/xmltv/

The system requirements are Perl 5.8.3 or later, and a few Perl modules. You will be asked about some optional components; if you choose not to install them then there are fewer dependencies.

Please note that in addition to the specific modules listed below, the tv_grab_zz_sdjson_sqlite grabber requires Perl 5.16 to be installed.

Required distributions/modules

Required distributions/modules for XMLTV's core libraries are:

Date::Manip 5.42a
File::Slurp
JSON (see note below)
HTTP::Request
HTTP::Response
LWP 5.65
LWP::UserAgent
LWP::Protocol::https
Term::ReadKey
URI
XML::LibXML
XML::Parser 2.34
XML::TreePP
XML::Twig 3.28
XML::Writer 0.6.0

Required modules for grabbers/utilities are:

CGI                           (tv_pick_cgi, core module until 5.20.3, part of CGI)
CGI::Carp                     (tv_pick_cgi, core module until 5.20.3, part of CGI)
Compress::Zlib                (for some of the grabbers, core module since 5.9.3, part of IO::Compress)
Data::Dump                    (for tv_grab_it_dvb)
Date::Format                  (for some of the grabbers, part of TimeDate)
DateTime                      (for several of the grabbers)
DateTime::Format::ISO8601     (tv_grab_zz_sdjson_sqlite)
DateTime::Format::SQLite      (tv_grab_zz_sdjson_sqlite)
DateTime::TimeZone            (tv_grab_fr)
DBD::SQLite                   (tv_grab_zz_sdjson_sqlite)
DBI                           (tv_grab_zz_sdjson_sqlite)
Digest::SHA                   (tv_grab_zz_sdjson{,_sqlite}, core module since 5.9.3)
File::HomeDir                 (tv_grab_zz_sdjson_sqlite)
File::Which                   (tv_grab_zz_sdjson_sqlite)
HTML::Entities 1.27           (for several of the grabbers, part of HTML::Parser 3.34)
HTML::Parser 3.34             (tv_grab_it, tv_grab_it_dvb, part of HTML::Parser 3.34)
HTML::Tree                    (for many of the grabbers, part of HTML::Tree)
HTML::TreeBuilder             (for many of the grabbers, part of HTML::Tree)
HTTP::Cache::Transparent 1.0  (for several of the grabbers)
HTTP::Cookies                 (for several of the grabbers)
IO::Scalar                    (for some of the grabbers, part of IO::Stringy)
List::MoreUtils               (tv_grab_zz_sdjson_sqlite)
LWP::Protocol::https          (tv_grab_fi, tv_grab_huro, tv_grab_zz_sdjson)
LWP::UserAgent::Determined    (tv_grab_zz_sdjson_sqlite)
SOAP::Lite 0.67               (tv_grab_na_dd)
Time::Piece                   (tv_grab_huro, core module since 5.9.5)
Time::Seconds                 (tv_grab_huro, core module since 5.9.5)
Tk                            (tv_check)
Tk::TableMatrix               (tv_check)
URI                           (for some of the grabbers, part of URI)
URI::Encode                   (tv_grab_pt_vodafone)
URI::Escape                   (for some of the grabbers, part of URI)
XML::DOM                      (tv_grab_is)
XML::LibXSLT                  (tv_grab_is)

When building XMLTV, any missing modules that are required for the selected grabbers/utilities will be reported.

Recommended distributions/modules

The following modules are recommended but XMLTV works without them installed:

File::chdir                      (testing grabbers)
JSON::XS                         (faster JSON handling, see note below)
Lingua::Preferred 0.2.4          (helps with multilingual listings)
Log::TraceMessages               (useful for debugging, not needed for normal use)
PerlIO::gzip                     (can make tv_imdb a bit faster)
Term::ProgressBar                (displays pretty progress bars)
Unicode::String                  (improved character handling in tv_to_latex)
URI::Escape::XS                  (faster URI handling)

JSON libraries

By default, libraries and grabbers that need to handle JSON data should specify the JSON module. This module is a wrapper for JSON::XS-compatible modules and supports the following JSON modules:

JSON::XS
JSON::PP
Cpanel::JSON::XS

JSON will use JSON::XS if available, falling back to JSON::PP (a core module since 5.14.0) if JSON::XS is not available. Cpanel::JSON::XS can be used as an explicit alternative by setting the PERL_JSON_BACKEND environment variable (please refer to the JSON module's documentation for details).

CPAN

All required modules can be quickly installed from CPAN using the cpanm utility. For example:

% cpanm XML::Twig

Please note that you may find it easier to search for packaged versions of required modules, as sources which distribute a packaged version of XMLTV also provide packaged versions of required modules.

Proxy servers

Proxy server support is provide by the LWP modules. You can define a proxy server via the HTTP_PROXY environment variable.

% HTTP_PROXY=http://somehost.somedomain:port

For more information, see this article

Known issues

If a full HTTP URL to the XMLTV.dtd is provided in the DOCTYPE declaration of an XMLTV document, please be aware that it is possible for the link to instead redirect to a page for accepting cookies. Such cookie-acceptance pages are more common in Europe, and can result in applications being unable to parse the file.

License

XMLTV is free software, distributed under the GNU General Public License, version 2. Please see COPYING for more details.

Authors

There have been many contributors to XMLTV. Where possible they are credited in individual source files and in the authors mapping file.

Resources

GitHub

Our GitHub project contains all source code, issues and Pull Requests.

Project Wiki

We have a project web page and wiki

Mailing Lists

We run the following mailing lists:

IRC

We run an IRC channel #xmltv on Libera Chat. Please join us!

-- Nick Morrott, knowledgejunkie@gmail.com, 2024-02-24