.\" 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_ZZ_SDJSON_SQLITE 1p" .TH TV_GRAB_ZZ_SDJSON_SQLITE 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_zz_sdjson_sqlite \- Grab TV and radio program listings from Schedules Direct (subscription required). .SH "SYNOPSIS" .IX Header "SYNOPSIS" tv_grab_zz_sdjson_sqlite \-\-help .PP tv_grab_zz_sdjson_sqlite \-\-info .PP tv_grab_zz_sdjson_sqlite \-\-version .PP tv_grab_zz_sdjson_sqlite \-\-capabilities .PP tv_grab_zz_sdjson_sqlite \-\-description .PP tv_grab_zz_sdjson_sqlite \-\-manage\-lineups [\-\-config\-file \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .PP tv_grab_zz_sdjson_sqlite [\-\-days N] [\-\-offset N] [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .PP tv_grab_zz_sdjson_sqlite \-\-configure [\-\-config\-file \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .PP tv_grab_zz_sdjson_sqlite \-\-list\-channels [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .PP tv_grab_zz_sdjson_sqlite \-\-list\-lineups [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .PP tv_grab_zz_sdjson_sqlite \-\-get\-lineup [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-quiet] [\-\-debug] [\-\-passwordhash \s-1HASH\s0] .SH "DESCRIPTION" .IX Header "DESCRIPTION" Output \s-1TV\s0 listings in \s-1XMLTV\s0 format for many locations available in North America (\s-1US/CA\s0) and other selected countries internationally. The data comes from and an account must be created on the Schedules Direct site in order to grab data. Refer to the Schedules Direct site for signup requirements and supported locations. .PP This grabber uses a shared local database which allows for downloading only new/changed/updated information, and in the case of mixed \s-1OTA,\s0 Cable, and/or Satellite providers can substantially reduce the download times (as some data such as schedules and program details are commonly shared between sources in the same location). .PP First, you must run \fBtv_grab_zz_sdjson_sqlite \-\-manage\-lineups\fR to manage the lineups available to your grabber configuration at the Schedules Direct service. .PP Second, you must run \fBtv_grab_zz_sdjson_sqlite \-\-configure\fR to choose which lineup this configuration will grab (this grabber will share the downloaded information for multiple lineups, and can substantially reduce the royal overheads in those cases). .SH "OPTIONS" .IX Header "OPTIONS" \&\fB\-\-manage\-lineups\fR Perform Schedules Direct lineup management functions (adding/deleting lineups from your account, and creating the local \s-1EPG\s0 database). Managing lineups can be performed without a configuration file (it will prompt for the needed information) but if it exists, it will be used to obtain initial credentials. If you change your password at Schedules Direct, you will need to update the database (or display the new password hash) using \-\-manage\-lineups. .PP \&\fB\-\-configure\fR Prompt for which lineup to download and write the configuration file. Note that one must run \-\-manage\-lineups first to create and initialize the database and configure lineups. .PP \&\fB\-\-config\-file \s-1FILE\s0\fR Set the name of the configuration file, the default is \fB~/.xmltv/tv_grab_zz_sdjson_sqlite.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\-\-download\-only\fR Perform a download of the data only (no output). .PP \&\fB\-\-no\-download\fR Do not download data, but use the existing contents of the local database. Since the code optimizes the data downloaded, this is nominally useful only in offline situations. .PP \&\fB\-\-force\-download\fR Deletes most existing local database data and forces a download of the data. If there is a suspicion that the data is currupt (and not being automatically corrected), forcing a new download might be necessary. .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. .PP \&\fB\-\-quiet\fR Suppress various informational messages shown on standard error. .PP \&\fB\-\-debug\fR Provide more information on progress to stderr to help in debugging. This can get very verbose, but too much data is better that not enough if errors need to be squashed. Note that the debug data may contain information you might prefer to be confidential such as your password hash, so treat the output appropriately. .PP \&\fB\-\-passwordhash \s-1HASH\s0\fR Provide the password hash on the command line. This is necessary if the hash is not stored in the database. .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. Note that list-lineups is not fully standardized, so the output is subject to change. .PP \&\fB\-\-get\-lineup\fR Write output giving elements for every channel available in the current lineup. Note that get-lineup is not fully standardized, so the output is subject to change. .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 signup for an account at Schedules Direct. This is a paid service providing \s-1EPG\s0 data for North America and other selected countries. See for signup requirements, and the countries served. .PP 2. Second you need to configure the lineups that you will have access to using your account with this grabber. Run \&\fBtv_grab_zz_sdjson_sqlite \-\-manage\-lineups\fR to add your lineups and to initialize the database. .PP 3. Third, you will need to configure this specific instance of the grabber to select the lineup to use. Run \&\fBtv_grab_zz_sdjson_sqlite \-\-configure\fR. .PP 4. (Optionally) run \fBtv_grab_zz_sdjson_sqlite \-\-download\-only\fR to download and \*(L"fill\*(R" the local database copies of your data. In future runs, only updated information will be downloaded, and the local database will be pruned to delete old/obsolete information. .SH "USAGE" .IX Header "USAGE" All the normal \s-1XMLTV\s0 capabilities are included. .PP Note that Schedules Direct only has data for a maximum of about 21 days, (although may be less for some channels) but the accuracy of the data at the end of the period tends to be poor. .SH "ERROR HANDLING" .IX Header "ERROR HANDLING" If the grabber encounters a fatal error, it will write a message to \&\s-1STDERR\s0 and \fIexit\fR\|(1). Some errors are retriable, and the code performs retries. .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" Schedules Direct lineups should support all the channels from your provider or \s-1OTA\s0 antenna. If there are missing channels, or incorrect guide data, you should contact Schedules Direct to request updates. .SH "XMLTV VALIDATION" .IX Header "XMLTV VALIDATION" \&\fBtv_validate_grabber\fR may report an error similar to: .PP .Vb 1 \& "Line 123 Duplicate channel\-tag for \*(AqI12345.json.schedulesdirect.org\*(Aq" .Ve .PP This is a because at least some providers (typically Cable/Satellite, but sometimes \s-1OTA\s0 repeaters that you may have in your lineup) actually have the exact same station available on multiple channels. \s-1XMLTV\s0 does not like seeing the same station reported twice, even though the full display-name info does show that the channel number is different. .PP This error can (should/must?) be ignored. .SH "XMLTV STATIONS vs CHANNELS" .IX Header "XMLTV STATIONS vs CHANNELS" \&\s-1XMLTV \s0(despite a couple of proposals to update the specifications) has a legacy confusion regarding the differences between a \*(L"station\*(R", which is a supplier of content (programs) and schedules, and a \&\*(L"channel\*(R" which is method of delivery/transport. \s-1XMLTV\s0 uses the term where they likely should be using the term , because they deal with programming, not transport. Regardless, such a transition would be understandably be a challenge, and the lineup proposals to extend the capability to provide a mechanism to support \*(L"channels\*(R" has not progressed in years. .PP This also results in a failing of the configuration capability which treats the selecting of content as being station based, which is not always the same thing as a (for example, for Cable providers, a \*(L"station\*(R" may be transmitted on many \&\*(L"channels\*(R" (perhaps in different resolutions), but an individual may only be authorized to receive some of the \*(L"channels\*(R"). One may want the \*(L"station\*(R" schedules and programs, but not to see the \*(L"channel\*(R" returned because they cannot tune it. .SH "CHANNEL SELECTION" .IX Header "CHANNEL SELECTION" Due to the \s-1XMLTV\s0 interpretations of , this grabber implements its own \*(L"channel\*(R" (transport) selection mechanism (which parallels that on the Schedules Direct site). It is implemented within the \-\-manage\-lineups capability. The grabber defaults will result in all channels and stations associated with the lineup being written. In some cases it may be desired by some to limit the channels to a small subset of all available channels (the most common being a Cable or Satellite service which has billions and billions of channels, but you are subscribed to a significantly reduced programming tier, and your application does not have the ability to restrict the display/access to that large number of channels). There is just enough flexibility to allow one to confuse oneself some of the time. Note that while an effort is made to maintain the existing selection value when the lineup mapping (channels and stations) are updated, new or changed station assignments per channel will result in the lineup defaults being assigned to the new or updated channel. The lineup channel selection default can also be set for an existing lineup. Due to the potential of future surprises or confusion, if one can avoid using the channel selection capability one is likely better off. .SH "FAQs" .IX Header "FAQs" No FAQs yet.... .SH "DISCLAIMER" .IX Header "DISCLAIMER" The Schedules Direct service requires a subscription, and only allows for usage for personal use with approved open source projects. Refer to the Schedules Direct site for their requirements and how to sign up. .SH "AUTHOR" .IX Header "AUTHOR" Gary Buhrmaster. As with most tv_grabbers, documentation, ideas, and parts of the code may have been leveraged from other existing grabbers from the XMLTV-project. We stand on the shoulders of those that came before us. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2016 Gary Buhrmaster .PP This code is distributed under the \s-1GNU\s0 General Public License v2 (GPLv2) .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. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA 02110\-1301, USA.\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIxmltv\fR\|(5).