.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "TV_GRAB_UK_ATLAS 1p" .TH TV_GRAB_UK_ATLAS 1p "2016-11-23" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" tv_grab_uk_atlas \- Grab TV and radio programme listings for UK from MetaBroadcast website (Atlas database). .SH "SYNOPSIS" .IX Header "SYNOPSIS" tv_grab_uk_atlas \-\-help .PP tv_grab_uk_atlas \-\-info .PP tv_grab_uk_atlas \-\-version .PP tv_grab_uk_atlas \-\-capabilities .PP tv_grab_uk_atlas \-\-description .PP tv_grab_uk_atlas [\-\-days N] [\-\-offset N] [\-\-dst] [\-\-channel S] [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .PP tv_grab_uk_atlas \-\-hours N [\-\-offset N] [\-\-channel S] [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .PP tv_grab_uk_atlas \-\-date \s-1DATE\s0 [\-\-dst] [\-\-channel S] [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .PP tv_grab_uk_atlas \-\-configure [\-\-config\-file \s-1FILE\s0] .PP tv_grab_uk_atlas \-\-configure\-api [\-\-stage \s-1NAME\s0] [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] .PP tv_grab_uk_atlas \-\-list\-channels [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .PP tv_grab_uk_atlas \-\-list\-lineups [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .PP tv_grab_uk_atlas \-\-get\-lineup [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] .SH "DESCRIPTION" .IX Header "DESCRIPTION" Output \s-1TV\s0 listings in \s-1XMLTV\s0 format for many channels available in \s-1UK.\s0 The data come from .PP First you must run \fBtv_grab_uk_atlas \-\-configure\fR to choose which channels you want to receive. .PP Then running \fBtv_grab_uk_atlas\fR with no arguments will get a listings in \s-1XML\s0 format for the channels you chose for available days including today. .SH "OPTIONS" .IX Header "OPTIONS" \&\fB\-\-configure\fR Prompt for which channels to download and write the configuration file. .PP \&\fB\-\-config\-file \s-1FILE\s0\fR Set the name of the configuration file, the default is \fB~/.xmltv/tv_grab_uk_atlas.conf\fR. This is the file written by \&\fB\-\-configure\fR and read when grabbing. .PP \&\fB\-\-output \s-1FILE\s0\fR When grabbing, write output to \s-1FILE\s0 rather than standard output. .PP \&\fB\-\-hours N\fR When grabbing, grab N hours of data. .PP \&\fB\-\-days N\fR When grabbing, grab N days rather than all available days. .PP \&\fB\-\-offset N\fR Start grabbing at today/now + N days. When \fB\-\-hours\fR is used this is number of hours instead of days. N may be negative. .PP \&\fB\-\-date N\fR Grab just this date (instead of days/offset). .PP \&\fB\-\-dst\fR Some PVRs have trouble with \s-1BST\s0 times and \*(L"lose\*(R" an hour at the end of the day schedule. This adds an extra hour to the schedule fetched. .PP \&\fB\-\-channel S\fR Grab just this channel (ignore the channels in the config file). Can be specified either as Atlas channel id (e.g. \*(L"cbbw\*(R") or mapped channel name (e.g. \*(L"south.bbc1.bbc.co.uk\*(R"). .PP \&\fB\-\-quiet\fR Suppress the progress-bar normally shown on standard error. .PP \&\fB\-\-debug\fR Provide more information on progress to stderr to help in debugging. .PP \&\fB\-\-list\-channels\fR Write output giving elements for every channel available in the current configuration. .PP \&\fB\-\-list\-lineups\fR Write output giving list of available viewing regions. .PP \&\fB\-\-get\-lineup\fR Write output giving elements for every channel available in the current lineup. .PP \&\fB\-\-capabilities\fR Show which capabilities the grabber supports. For more information, see .PP \&\fB\-\-version\fR Show the version of the grabber. .PP \&\fB\-\-help\fR Print a help message and exit. .PP \&\fB\-\-info\fR Print a help page and exit. .SH "INSTALLATION" .IX Header "INSTALLATION" 1. First you must obtain an Atlas \s-1API\s0 key from MetaBroadcast. This is free (at the present time) for personal use and is necessary to allow you to access the full schedule published by the Press Association. Any commercial use of the data obtained from Atlas will require a paid-for license. .PP Instructions are available here: .PP You will need to enter your \s-1API\s0 key during the \-\-configure stage. .PP Remember to request Press Association (\s-1PA\s0) as the content provider on your Atlas \s-1API\s0 key. .PP 2. Grabber configuration consists of the usual: \&\fBtv_grab_uk_atlas \-\-configure\fR .PP Atlas have regionalised data which means you can obtain listings specific to your \&\s-1TV\s0 region. When you run the \-\-configure option you will be asked which viewing platform (e.g. Freeview; Sky \s-1HD\s0) and region (e.g. London; South East) you wish to access. (You can select only 1 region!). .PP Then you select which channels you want to fetch. .PP 3. The file \fItv_grab_uk_atlas.user.map.conf\fR has two purposes. Firstly you can map the channel ids used by Atlas into something more meaningful to your \s-1PVR. E\s0.g. .PP .Vb 1 \& map==cbdm==FILM4 .Ve .PP will change \*(L"cbdm\*(R" to \*(L"\s-1FILM4\*(R"\s0 in the output \s-1XML.\s0 .PP Note: the lines are of the form \*(L"map=={channel id}=={my name}\*(R". .PP The second purpose is to likewise translate genre names. So if your \s-1PVR\s0 doesn\*(L"t have a category for \*(R"Science Fiction\*(L" but uses \*(R"Sci-fi" instead, then you can specify .PP .Vb 1 \& cat==Science Fiction==Sci\-fi .Ve .PP and the output \s-1XML\s0 will have \*(L"Sci-fi\*(R". .PP \&\s-1IMPORTANT:\s0 the downloaded \*(L"tv_grab_uk_atlas.user.map.conf\*(R" contains example lines to illustrate the format \- you should edit this file to suit your own purposes! .SH "USAGE" .IX Header "USAGE" All the normal \s-1XMLTV\s0 capabilities are included but there is an additional parameter \&\*(L"\-\-hours\*(R". Atlas allows schedule data to be retrieved either by number-of-days or by number-of-hours. .PP Where possible you should use this \*(L"hours\*(R" facility to reduce unnecessary load on the Atlas server. .PP When \-\-hours is specified the \-\-offset is interpreted as hours. .PP For example: .PP .Vb 1 \& \- to retrieve a schedule for the next 12 hours: \& \& tv_grab_uk_atlas \-\-hours 12 \& \& \- to retrieve a schedule for the next 12 hours starting tomorrow: \& \& tv_grab_uk_atlas \-\-hours 12 \-\-offset 24 .Ve .PP Alternatively you can use the familiar \*(L"days\*(R" format: .PP .Vb 1 \& tv_grab_uk_atlas \-\-days 1 \& \& tv_grab_uk_atlas \-\-days 1 \-\-offset 1 .Ve .PP Negative numbers are allowed, so for example the following are valid: .PP .Vb 1 \& tv_grab_uk_atlas \-\-offset \-4 \-\-hours 12 \& \& tv_grab_uk_atlas \-\-offset \-1 \-\-days 1 .Ve .PP Note that Atlas only has data for a maximum 14 days ahead and it varies; some channels have less than this. .PP An additional parameter \*(L"\-\-date \s-1YYYYMMDD\*(R"\s0 allows you to fetch the schedule just for this date. (This is obviously similar to \-\-days 1 with an appropriate \&\-\-offset but avoids you having to calculate the offset; this is easier for some automated fetchers.) E.g. .PP .Vb 1 \& tv_grab_uk_atlas \-\-date 20130923 .Ve .PP A new parameter \*(L"\-\-dst\*(R" allows you to add an extra hour to the schedule fetched from Atlas. Some PVRs have trouble with \s-1BST\s0 times and \*(L"lose\*(R" an hour at the end of the day"s schedule. This parameter might help to alleviate that. .PP .Vb 1 \& tv_grab_uk_atlas \-\-days 1 \-\-dst .Ve .PP A new parameter \*(L"\-\-channel\*(R" allows you to override the config file and retrieve data for a specific channel: .PP .Vb 1 \& tv_grab_uk_atlas \-\-offset \-4 \-\-hours 12 \-\-channel cbdm .Ve .SH "BROWSER INTERFACE" .IX Header "BROWSER INTERFACE" If you wish to run the fetcher via a browser then you can install the supplied cgi script. .PP (Note you must obviously have a webserver installed or be using a web-host for this to work.) .PP Copy the file \fIgetatlas.pl\fR into the cgi-enabled directory on your web space. (Hint: This directory is often called \*(L"cgi-bin\*(R".) Ensure the file has execute permission. .PP (Tech note: use a \*(L"normal\*(R" cgi handler to run this file; fastcgi may not work.) .PP Specify the parameters on the \s-1URI\s0 as follows: offset=xxxx hours=xxxx days=xxxx date=YYYYMMDD channel=xxxx dst .PP .Vb 5 \& e.g. \& http://my.webspace.com/cgi\-bin/getatlas.pl?hours=12 \& http://my.webspace.com/cgi\-bin/getatlas.pl?hours=12&offset=6 \& http://my.webspace.com/cgi\-bin/getatlas.pl?date=20130930 \& http://my.webspace.com/cgi\-bin/getatlas.pl?days=1&dst .Ve .PP Valid combinations are: \*(L"offset\*(R" and \*(L"hours\*(R" or \*(L"offset\*(R" and \*(L"days\*(R" \- in which case the offset is \*(L"days\*(R" also (otherwise it\*(L"s \*(R"hours\*(L") or \*(R"date" \- fetch just this day .SH "ERROR HANDLING" .IX Header "ERROR HANDLING" If the grabber fails to download data for some channel on a specific day, it will print an errormessage to \s-1STDERR\s0 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. .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" The environment variable \s-1HOME\s0 can be set to change where configuration files are stored. All configuration is stored in \f(CW$HOME\fR/.xmltv/. On Windows, it might be necessary to set \s-1HOME\s0 to a path without spaces in it. .SH "SUPPORTED CHANNELS" .IX Header "SUPPORTED CHANNELS" For information on supported channels, see the tv_grab_uk_atlas.map.channels.conf file in your \f(CW$HOME\fR/.xmltv/supplement/tv_grab_uk_atlas/ directory after you have run the grabber at least once. .SH "XMLTV VALIDATION" .IX Header "XMLTV VALIDATION" \&\fBtv_validate_grabber\fR may report an error similar to: .PP .Vb 1 \& "Line 5 Invalid channel\-id BBC 1" .Ve .PP This is a because ValidateFile.pm insists the channel-id adheres to \s-1RFC2838 \s0 despite the xmltv.dtd only saying \*(L"preferably\*(R" not \*(L"\s-1SHOULD\*(R". \&\s0(Having channel ids of the form \*(L"bbc1.bbc.co.uk\*(R" will be rejected by many PVRs since they require the data to match their own list.) .PP This error can be ignored. .SH "FAQs" .IX Header "FAQs" 1. What does \*(L"Enter your Atlas \s-1API\s0 key\*(R" mean? .PP You must obtain an \s-1API\s0 key free from Atlas MetaBroadcast before you can use this grabber. Instructions are available here: .PP 2. I\*(L"m getting the error \*(R"Status: 400 Bad Request" .PP Typically this is because you haven\*(L"t entered your \s-1API\s0 key during the \&\-\-configure stage. Or your \s-1API\s0 key does not allow access to Press Association data (log-in to your account at http://atlas.metabroadcast.com/admin and \*(R"Request Access\*(L" to \*(R"\s-1PA" \s0 source data). Or if you requested a particular channel with the \-\-channel option but the channel cannot be found. .SH "DISCLAIMER" .IX Header "DISCLAIMER" The MetaBroadcast free license for these data does not allow non-personal use. .PP 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. .PP 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. .SH "AUTHOR" .IX Header "AUTHOR" Geoff Westcott. This documentation and parts of the code based on various other tv_grabbers from the XMLTV-project. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2013 Geoff Westcott. .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License (version 2) as published by the Free Software Foundation. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \&\s-1GNU\s0 General Public License for more details. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIxmltv\fR\|(5).