.\" 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_NA_DD 1p" .TH TV_GRAB_NA_DD 1p "2017-01-24" "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_na_dd \- Grab TV listings for North America using Schedules Direct http://www.schedulesdirect.org .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& tv_grab_na_dd \-\-help \& \& tv_grab_na_dd \-\-version \& \& tv_grab_na_dd \-\-capabilities \& \& tv_grab_na_dd \-\-configure [\-\-config\-file FILE] [\-\-dd\-data FILE] \& [\-\-reprocess] [\-\-auto\-config add|ignore] \& [\-\-gui OPTION] \& \& tv_grab_na_dd \-\-list\-lineups [\-\-config\-file FILE] [\-\-dd\-data FILE] \& [\-\-reprocess] \& \& tv_grab_na_dd [\-\-config\-file FILE] [\-\-dd\-data FILE] \& [\-\-reprocess] [\-\-auto\-config add|ignore] \& [\-\-days N] [\-\-offset N] [\-\-quiet] [\-\-notrim] \& [\-\-old\-chan\-id] [\-\-low\-mem] [\-\-output FILE] \& [\-\-list\-channel] [\-\-share SHAREDIR] [\-\-list\-times] \& [\-\-download\-only] [\-\-padd n] [\-\-dropbadchar] [\-\-agent NAME] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This script downloads \s-1TV\s0 listings using Schedules Direct's data service, converts it to \s-1XMLTV\s0 format, and outputs the results. .PP You must first register with Schedules Direct at: .PP Schedules Direct is a non-profit organization whose mission is to provide low-cost television program guide data to end-users of Open Source and Freeware applications. .PP The raw data source is Schedules Direct's SD-DD service, which purchases Data from Gracenote (formerly known as Tribune Media Services). .PP While the service is not available for free, Schedules Direct strives to keep costs as low as possible. .PP First you must become a member at the site. .PP Next, you use that website to add lineup(s) to your account. .PP Next, you execute \f(CW\*(C`tv_grab_na_dd \-\-configure\*(C'\fR to set up the grabber. .PP Finally, you execute \fBtv_grab_na_dd\fR with no arguments and it will output listings in \s-1XML\s0 format to standard output. See below for other options. .PP Like many utilities, tv_grab_na_dd tries to exit with a \*(L"0\*(R" on success and something else on error. .SH "Stand-alone options" .IX Header "Stand-alone options" .IP "\-\-help" 4 .IX Item "--help" Print a help message and exit. .IP "\-\-version" 4 .IX Item "--version" Show the version of the grabber. .IP "\-\-capabilities" 4 .IX Item "--capabilities" Show which capabilities the grabber supports. For more information, see .SH "Mode selection (default is grab mode)" .IX Header "Mode selection (default is grab mode)" .IP "\-\-configure" 4 .IX Item "--configure" Activates configure mode. If a config file already exists the values are used as defaults. .IP "\-\-gui \s-1OPTION\s0" 4 .IX Item "--gui OPTION" Use this option to enable a graphical interface to be used. \&\s-1OPTION\s0 may be 'Tk', or left blank for the best available choice. Additional allowed values of \s-1OPTION\s0 are 'Term' for normal terminal output (default) and 'TermNoProgressBar' to disable the use of Term::ProgressBar. .IP "\-\-list\-lineups" 4 .IX Item "--list-lineups" Lists available lineups. Only requires username in the config file. Used by programs that automate the \*(L"\-\-configure\*(R" process. .SH "General Options" .IX Header "General Options" .IP "\-\-config\-file \fIfile\fR" 4 .IX Item "--config-file file" Set the name of the configuration file, the default is \fB~/.xmltv/tv_grab_na_dd.conf\fR. This is the file created during \*(L"\-\-configure\*(R" mode. .IP "\-\-dd\-data \fIfile\fR" 4 .IX Item "--dd-data file" Store raw Data Direct data to this file. (default is a temporary file) .IP "\-\-reprocess" 4 .IX Item "--reprocess" Don't get data from Data Direct, but reprocess a file saved with \-\-dd\-data. .IP "\-\-auto\-config \fIadd|ignore\fR" 4 .IX Item "--auto-config add|ignore" When used in \-\-configure mode, updates the config file, removing old channels, and adding or ignoring new channels. Prompts are skipped if defaults are available in the current config file. .Sp When used in grab mode, appends new channels to the config file. .SH "Grabber Mode options" .IX Header "Grabber Mode options" .IP "\-\-days \fIn\fR" 4 .IX Item "--days n" Grab \fIn\fR days. The default is 7. .IP "\-\-offset \fIn\fR" 4 .IX Item "--offset n" Start N days after the default. .IP "\-\-quiet" 4 .IX Item "--quiet" Suppress some messages normally written to standard error. .IP "\-\-notrim" 4 .IX Item "--notrim" Data Direct includes shows in progress at the start time. The default behavior is to filter these shows out so data can be cleanly split between days. This option turns off that filter so you get shows in progress a tthe start time. .IP "\-\-old\-chan\-id" 4 .IX Item "--old-chan-id" Use a channel id similar to the one used by the old \fBtv_grab_na\fR grabber. .IP "\-\-low\-mem" 4 .IX Item "--low-mem" Omit all but the most basic program information. Reduces memory usage. .IP "\-\-output \fIfile\fR" 4 .IX Item "--output file" Write xml to \fIfile\fR rather than standard output. .IP "\-\-list\-channel" 4 .IX Item "--list-channel" Same as \fB\-\-days\fR 0 .IP "\-\-share \fI\s-1SHAREDIR\s0\fR" 4 .IX Item "--share SHAREDIR" tv_grab_na_icons stores icons in \fI\s-1SHAREDIR\s0\fR/icons. The share directory is set at install time, but there may be times when it needs to be specified. (for example: no write access to the default share directory) .IP "\-\-list\-times" 4 .IX Item "--list-times" Report to \s-1STDERR\s0 the Schedules Direct blockedTime (not currently enforced) and suggestedTime values to assist automated processes with scheduling. .IP "\-\-download\-only" 4 .IX Item "--download-only" Don't generate any output, just fetch the data. Personally I don't see the point, but it was requested and easy to add. .IP "\-\-padd \fIn\fR" 4 .IX Item "--padd n" Add spaces to the front of the start date. This is normally not needed, but can be helpful in working around a SD-DD problem when the request packet spans \s-1TCP\s0 packets. Recommended initial value is \*(L"20\*(R". This is only needed if you get \&\*(L"invalid start time\*(R" messages. If this helps, please post results to the list. .IP "\-\-dropbadchar" 4 .IX Item "--dropbadchar" \&\s-1DD\s0 data is supposed to be in \s-1UTF\-8\s0 format. Sometimes \s-1DD\s0 sends bad characters which cause a \*(L"Bad \s-1XML\s0 from \s-1DD\*(R"\s0 error. This option causes those bad characters to be deleted. .IP "\-\-agent \s-1NAME\s0" 4 .IX Item "--agent NAME" appends \s-1NAME\s0 to the http agent string when fetching data. This is a polite way to tell Schedules Direct which application is being used. It helps developers know how many people are using their application and gives applications credit towards free accounts. .SH "Automating configuration" .IX Header "Automating configuration" Sometimes applications want to call \fBtv_grab_na_dd\fR as a standalone application, but automate the configure process. The best way is to hook in to the XMLTV::Ask module, but if that's not available, here is a solution. .Sp .RS 4 Step1. Application creates config file with username (and optionally password). .Sp Step2. \f(CW\*(C`tv_grab_na_dd \-\-dd\-data lineups.xml \-\-list\-lineups\*(C'\fR .Sp Step3. Application adds desired lineup to config file. .Sp Step4. \f(CW\*(C`tv_grab_na_dd \-\-dd\-data lineups.xml \-\-reprocess \-\-auto\-config add \-\-list\-channels\*(C'\fR .Sp Step5. Application edits config file as needed, and deletes lineups.xml. .RE .SH "Grabber Timing" .IX Header "Grabber Timing" Data Direct offers a \*(L"suggested download time\*(R" that can be retrieved with the \&\*(L"\-\-list\-times\*(R" option. Its use is encouraged. .SH "Handling Multiple Linups" .IX Header "Handling Multiple Linups" tv_grab_na_dd only outputs a single lineup. If your Schedules Direct account has multiple lineups, they are all downloaded even though only one is output. .PP To process multiple lineups, use separate \-\-config\-file. Separate config files are also handy if you need different channel sets for a lineup (common with MythTV). To prevent re-downloading the data on subsequent passes, the \&\*(L"\-\-reprocess\*(R" option is recommended. .PP Here's an example: (the = sign is optional, but helps readability) .PP .Vb 3 \& tv_grab_na_dd \-\-config\-file=lineup1.dat \-\-output=lineup1.xml \-\-dd\-data=dd.xml \& tv_grab_na_dd \-\-config\-file=lineup2.dat \-\-output=lineup2.xml \-\-dd\-data=dd.xml \-\-reprocess \& tv_grab_na_dd \-\-config\-file=lineup3.dat \-\-output=lineup3.xml \-\-dd\-data=dd.xml \-\-reprocess .Ve .PP Each config file specifies the desired lineup and channel list. .PP If you want to merge the lineups into a single file, you can use tv_cat .PP .Vb 1 \& tv_cat lineup1.xml lineup2.xml lineup3.xml >guide.xml .Ve .SH "Adding icon links to listings" .IX Header "Adding icon links to listings" \&\fBtv_grab_na_dd\fR checks for channel icons in a directory \fB\f(BIshare\fB\fR/\fBicons\fR. The \fIshare\fR directory is usually set during the install. For windows exe users, it defaults to the location where \&\fBxmltv.exe\fR is. \fBtv_grab_na_icons\fR is available to download the icons. .SH "Notes on channel lists" .IX Header "Notes on channel lists" Channel lists can be configured both at the Schedules Direct website and through the grabber. This is done to allow multiple config files with different channel lists as Schedules Direct only supports a single channel map per lineup. .PP Similarly, tv_grab_na_dd only supports a single channel mapping for a station. If multiple mappings are detected, only the first one is used and you are advised to adjust your Schedules Direct lineup. .SH "Notes on episode numbers" .IX Header "Notes on episode numbers" Three episode-num formats are supplied (when available) .IP "xmltv_ns" 4 .IX Item "xmltv_ns" always \f(CW\*(C`..a/b\*(C'\fR for part \f(CW\*(C`a\*(C'\fR of \f(CW\*(C`b\*(C'\fR. First two xmltv_ns fields always blank. .IP "dd_progid" 4 .IX Item "dd_progid" Gracenote generated \f(CW\*(C`a.b.c/d\*(C'\fR where \f(CW\*(C`a\*(C'\fR is a unique program id, \f(CW\*(C`b\*(C'\fR is a unique episode id, \&\f(CW\*(C`c/d\*(C'\fR is part \f(CW\*(C`c\*(C'\fR of \f(CW\*(C`d\*(C'\fR similar to xmltv_ns. .IP "onscreen" 4 .IX Item "onscreen" Distributor-designated number corresponding to an episode of a specific show. Varies by distributor. .SH "Notes on passwords" .IX Header "Notes on passwords" If a password is stored in the config file, the config file should be properly protected. Instead of storing the password in the config file, it can be omitted, and will be prompted for. .SH "Notes on lineup changes" .IX Header "Notes on lineup changes" Data Direct currently adds a channel to your lineup automatically when it is available. When \&\fBtv_grab_na_dd\fR sees the new channel in the Schedules Direct lineup, it prints a message (and potentially adds or ignores it based on \-\-auto\-config). .PP If you are sensitive to bandwidth issues, I would set \fB\-\-auto\-config ignore\fR and periodically check your \fB\-\-config\-file\fR for ignored channels and remove from your Schedules Direct lineup. .SH "Notes on previously-shown" .IX Header "Notes on previously-shown" Previous releases of tv_grab_na_dd set \s-1XMLTV\s0's \*(L"date\*(R" field for \s-1DD \s0\*(L"original-air-date\*(R" field. The correct place for the data is \*(L"previously\-shown\->start\*(R" The \s-1OAD\s0 is in both places temporarily for compatibility reasons. .PP \&\s-1DD\s0 has dropped the \*(L"repeat\*(R" flag and replaced it with a \*(L"new\*(R" flag. Now we set "previously-shown .SH "Known issues" .IX Header "Known issues" none! .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIxmltv\fR\|(5). .SH "Author" .IX Header "Author" Author/Maintainer: Robert Eden, rmeden@yahoo.com .SS "Contributors:" .IX Subsection "Contributors:" .RS 4 Ed Avis, ed@membled.com .Sp Don Huettl, drh@huettl.net .Sp Matti Airas, mairas@iki.fi (I used tv_grab_fi as a template) .Sp and of course everyone else I forgot to mention. :) .RE