NAME

       tv_grab_uk_tvguide - Grab TV listings for UK from the TVGuide website.

SYNOPSIS

       tv_grab_uk_tvguide --usage

       tv_grab_uk_tvguide --version

       tv_grab_uk_tvguide --configure [--config-file FILE] [--gui OPTION] [--method N]
                          [--makeignorelist FILE] [--useignorelist FILE] [--debug]

       tv_grab_uk_tvguide [--config-file FILE] [--output FILE] [--days N]
                          [--offset N] [--nodetailspage]  [--legacychannels]
                          [--quiet] [--debug]

       tv_grab_uk_tvguide --list-channels [--output FILE] [--method N] [--debug]

DESCRIPTION

       Output TV listings in XMLTV format for many channels available in UK.  The data come from
       tvguide.co.uk

       First you must run tv_grab_uk_tvguide --configure to choose which channels you want to
       receive.

       Then running tv_grab_uk_tvguide with no arguments will get programme listings in XML
       format for the channels you chose, for available days including today.

OPTIONS

       --configure Prompt for which channels to fetch the schedule for, and write the
       configuration file.

       --config-file FILE Set the name of the configuration file, the default is
       ~/.xmltv/tv_grab_uk_tvguide.conf.  This is the file written by --configure and read when
       grabbing.

       --gui OPTION Use this option to enable a graphical interface to be used.  OPTION may be
       'Tk'.  Additional allowed values of OPTION are 'Term' for normal terminal output (default)
        and 'TermNoProgressBar' to disable the use of Term::ProgressBar.  (May not work on
       Windows OS.)

       --days N Grab N days. The default is 5 days.

       --offset N Start N days in the future.  The default is to start from today.

       --nodetailspage Only fetch summary information for each programme. (See discussion below).

       --legacychannels Channel ids were made compliant with the XMLTV specification in December
       2020. Use --legacychannels to output channel ids in the previous format
        (i.e. number only).

       --output FILE Write to FILE rather than standard output.

       --method N This program has three methods for fetching the list of channels available. The
       preferred method can be overridden with an option of either --method 1 or --method 2 to
       use one of the two alternative methods.

       If no --method parameter is supplied then the various methods will be tried in sequence
       until a channels list is obtained. A parameter of --method 0 will run the preferred method
       only.

       Normally you should omit this parameter.

       --makeignorelist FILE The source channel list contains many channels which have no
       programme listings available. By using a local file of channel ids these can be filtered
       out during the configure process. This option creates a list of channel ids which can be
       excluded from your config file

       makeignorelist can take over an hour to run but you only need run it infrequently (not
       every time you run --configure).

       --useignorelist FILE Specify the file containing a list of channel ids to be removed
       during the configure stage.

       This may be the file just created with --makeignorelist (e.g. --configure --makeignorelist
       myfile --useignorelist myfile )

       --quiet Suppress the progress messages normally written to the console.

       --debug Provide more information on progress to standard error to help in debugging.

       --list-channels Output a list (in xmltv format) of all channels that can be fetched.

       --version Show the version of the grabber.

       --usage Print a help message and exit.

INSTALLATION

       The file tv_grab_uk_tvguide.map.conf has two purposes.  Firstly you can map the channel
       ids used by the site into something more meaningful to your PVR. E.g.

             map==74==BBC 1

       will change "74" to "BBC 1" in the output XML.

       Note: the lines are of the form "map=={channel id}=={my name}".

       The second purpose is to likewise translate genre names.  So if your PVR doesn"t have a
       category for "Science Fiction" but uses "Sci-fi" instead, then you can specify

             cat==Science Fiction==Sci-fi

       and the output XML will have "Sci-fi".

       IMPORTANT: the downloaded "tv_grab_uk_tvguide.map.conf" contains example lines to
       illustrate the format - you should edit this file to suit your own purposes!

ERROR HANDLING

       If the grabber fails to download data for some channel on a specific day, it will print an
       errormessage to STDERR and then continue with the other channels and days. The grabber
       will exit with a status code of 1 to indicate that the data is incomplete.

ENVIRONMENT VARIABLES

       The environment variable HOME can be set to change where configuration files are stored.
       All configuration is stored in $HOME/.xmltv/. On Windows, it might be necessary to set
       HOME to a path without spaces in it.

SUPPORTED CHANNELS

       For information on supported channels, see http://tvguide.co.uk/

XMLTV VALIDATION

       tv_validate_grabber may report an error similar to:

             "Line 5 Invalid channel-id BBC 1"

       This is a because ValidateFile.pm insists the channel-id adheres to RFC2838 despite the
       xmltv.dtd only saying "preferably" not "SHOULD".  (Having channel ids of the form
       "bbc1.bbc.co.uk" will be rejected by many PVRs since they require the data to match their
       own list.)

       It may also report:

             "tv_sort failed on the concatenated data. Probably due to overlapping data between days."

       Both these errors can be ignored.

USING --nodetailspage

       This option may be useful if you have problems accessing the tvguide website: it will
       considerably speed up your grabbing, but at the expense of data richness.  The details
       page has a better list of actors, as well as director's names, film classifications, and
       background images.

       More significantly, the details page includes programme duration and programme end time.
       If you don't include the details page then your output programmes will not have stop
       times. Although stop times are an optional XMLTV element, many downstream programs expect
       them and break without them.

       Fortunately, these can be added by piping your xml file through the tv_sort filter: this
       will add stop times to all programmes except for the last programme on every channel. For
       example:

             tv_grab_uk_tvguide --days 3 --nodetailspage | tv_sort --by-channel --output myprogrammes.xml

       NOTE: As at January 2022 it seems the actor/director names and film classification is no
       longer present in the website, although it may be there for some channels(?).  Therefore
       you may find the --nodetailspage option useful to significantly reduce your run time.
       However, the details page does include background image(s) of the programme, which is not
       present in your xml file when using --nodetailspage

BE KIND

       If using the details page from the website then your grabbing might benefit from a more
       targeted strategy, rather than blithely getting all days for all channels.

       Since the published schedule rarely changes, a strategy of grabbing the next 3 days plus
       the 1 newest day would give you any new programmes as well as any last minute changes.
       Simply fetch "--offset 0 --days 3" and concatenate it with a separate fetch of "--offset 7
       --days 1".

       For example:

             ( tv_grab_uk_tvguide --days 3 --offset 0 --output temp.xml ) && ( tv_grab_uk_tvguide
             --days 1 --offset 7 | tv_cat --output myprogrammes.xml temp.xml - ) && ( rm -f
             temp.xml )

       A similar strategy could be employed when using --nodetailspage if you have a lot of
       channels:

             ( tv_grab_uk_tvguide --days 3 --offset 0 --nodetailspage | tv_sort --by-channel
             >temp.xml ) && ( tv_grab_uk_tvguide --days 1 --offset 7 --nodetailspage | tv_sort
             --by-channel | tv_cat --output myprogrammes.xml temp.xml - ) && ( rm -f temp.xml )

       This avoids overloading the TVGuide website, and significantly reduces your runtime with
       minimal impact on your viewing schedule.

       TVGuide provide this data for free, so let's not abuse their generosity.

DISCLAIMER

       The TVGuide website's license for these data does not allow non-personal use.

       Certainly, any commercial use of listings data obtained by using this grabber will breach
       copyright law, but if you are just using the data for your own personal use then you are
       probably fine.

       By using this grabber you aver you are using the listings data for your own personal use
       only and you absolve the author(s) from any liability under copyright law or otherwise.

AUTHOR

       Geoff Westcott. This documentation and parts of the code based on various other
       tv_grabbers from the XMLTV-project.

SEE ALSO

       xmltv(5).