Provided by: xmltv-util_1.2.1-1_all bug

NAME

       tv_grab_zz_sdjson_sqlite - Grab TV and radio program listings from Schedules Direct
       (subscription required).

SYNOPSIS

       tv_grab_zz_sdjson_sqlite --help

       tv_grab_zz_sdjson_sqlite --info

       tv_grab_zz_sdjson_sqlite --version

       tv_grab_zz_sdjson_sqlite --capabilities

       tv_grab_zz_sdjson_sqlite --description

       tv_grab_zz_sdjson_sqlite --manage-lineups [--config-file FILE]
                     [--quiet] [--debug] [--passwordhash HASH]

       tv_grab_zz_sdjson_sqlite [--days N] [--offset N] [--config-file FILE]
                     [--output FILE] [--quiet] [--debug]
                     [--passwordhash HASH]

       tv_grab_zz_sdjson_sqlite --configure [--config-file FILE]
                     [--quiet] [--debug]
                     [--passwordhash HASH]

       tv_grab_zz_sdjson_sqlite --list-channels [--config-file FILE]
                     [--output FILE] [--quiet] [--debug]
                     [--passwordhash HASH]

       tv_grab_zz_sdjson_sqlite --list-lineups  [--config-file FILE]
                     [--output FILE] [--quiet] [--debug]
                     [--passwordhash HASH]

       tv_grab_zz_sdjson_sqlite --get-lineup [--config-file FILE]
                     [--output FILE] [--quiet] [--debug]
                     [--passwordhash HASH]

DESCRIPTION

       Output TV listings in XMLTV format for many locations available in North America (US/CA)
       and other selected countries internationally.  The data comes from
       <http://www.schedulesdirect.org> 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.

       This grabber uses a shared local database which allows for downloading only
       new/changed/updated information, and in the case of mixed OTA, 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).

       First, you must run tv_grab_zz_sdjson_sqlite --manage-lineups to manage the lineups
       available to your grabber configuration at the Schedules Direct service.

       Second, you must run tv_grab_zz_sdjson_sqlite --configure 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).

OPTIONS

       --manage-lineups Perform Schedules Direct lineup management functions (adding/deleting
       lineups from your account, and creating the local EPG 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.

       --configure 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.

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

       --output FILE When grabbing, write output to FILE rather than standard output.

       --download-only Perform a download of the data only (no output).

       --no-download 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.

       --force-download Deletes most existing local database data and forces a download of the
       data.  If there is a suspicion that the data is corrupt (and not being automatically
       corrected), forcing a new download might be necessary.

       --days N When grabbing, grab N days rather than all available days.

       --offset N Start grabbing at today/now + N days.

       --quiet Suppress various informational messages shown on standard error.

       --debug 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.

       --passwordhash HASH Provide the password hash on the command line.  This is necessary if
       the hash is not stored in the database.

       --scale-download N Scale the download chunks from the default sizes. A value of .5 would
       reduce the sizes of the chunks requested by half.  The resulting number is bound between 1
       and the max value.

       --resturl URL Provide the Schedules Direct service endpoint URL.  This is primarily useful
       for testing.

       --list-channels Write output giving <channel> elements for every channel available in the
       current configuration.

       --list-lineups Write output giving list of available viewing regions.  Note that list-
       lineups is not fully standardized, so the output is subject to change.

       --get-lineup Write output giving <channel> elements for every channel available in the
       current lineup.  Note that get-lineup is not fully standardized, so the output is subject
       to change.

       --capabilities Show which capabilities the grabber supports. For more information, see
       <http://wiki.xmltv.org/index.php/XmltvCapabilities>

       --version Show the version of the grabber.

       --help Print a help message and exit.

       --info Print a help page and exit.

INSTALLATION

       1.  First you must signup for an account at Schedules Direct.  This is a paid service
       providing EPG data for North America and other selected countries.  See
       <http://www.schedulesdirect.org> for signup requirements, and the countries served.

       2.  Second you need to configure the lineups that you will have access to using your
       account with this grabber.  Run tv_grab_zz_sdjson_sqlite --manage-lineups to add your
       lineups and to initialize the database.

       3.  Third, you will need to configure this specific instance of the grabber to select the
       lineup to use.  Run tv_grab_zz_sdjson_sqlite --configure.

       4.  (Optionally) run tv_grab_zz_sdjson_sqlite --download-only to download and "fill" 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.

USAGE

       All the normal XMLTV capabilities are included.

       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.

ERROR HANDLING

       If the grabber encounters a fatal error, it will write a message to STDERR and exit(1).
       Some errors are retriable, and the code performs retries.

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.

       The environment variable TV_GRAB_TARGET_APPLICATION_FIXUPS can be set to indicate that the
       grabber should apply fixups for applications that are not fully XMLTV compliant, or that
       are currently missing some specific functionality.  The fixups can be combined by
       separating them with colons.  Available fixups are NO_XMLTV_NS_TOTAL_SEASONS (do not
       include the total seasons in the generated xmltv_ns episode numbering),
       NO_PREVIOUSLY_SHOWN_ZONE_OFFSET (do not include the zone offset in previously-shown), and
       NO_STATION_LOGOS (do not include station logos in the output).  The fixups are intended to
       be temporary until the application(s) can be updated.

SUPPORTED CHANNELS

       Schedules Direct lineups should support all the channels from your provider or OTA
       antenna.  If there are missing channels, or incorrect guide data, you should contact
       Schedules Direct to request updates.

XMLTV VALIDATION

       tv_validate_grabber may report an error similar to:

             "Line 123 Duplicate channel-tag for 'I12345.json.schedulesdirect.org'"

       This is because at least some providers (typically Cable/Satellite, but sometimes OTA
       repeaters that you may have in your lineup) actually have the exact same station available
       on multiple channels.  XMLTV does not like seeing the same station reported twice, even
       though the full display-name info does show that the channel number is different.

       This error can (should/must?) be ignored.

XMLTV STATIONS vs CHANNELS

       XMLTV (despite a couple of proposals to update the specifications) has a legacy confusion
       regarding the differences between a "station", which is a supplier of content (programs)
       and schedules, and a "channel" which is method of delivery/transport.  XMLTV uses the term
       <channel> where they likely should be using the term <station>, 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 "channels" has not progressed in years.

       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 <channel> (for
       example, for Cable providers, a "station" may be transmitted on many "channels" (perhaps
       in different resolutions), but an individual may only be authorized to receive some of the
       "channels").  One may want the "station" schedules and programs, but not to see the
       "channel" returned because they cannot tune it.

CHANNEL SELECTION

       Due to the XMLTV interpretations of <channel>, this grabber implements its own "channel"
       (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.

FAQs

       No FAQs yet....

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.

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.

COPYRIGHT

       Copyright (c) 2016, 2017, 2018, 2022 Gary Buhrmaster <gary.buhrmaster@gmail.com>

       This code is distributed under the GNU General Public License v2 (GPLv2)

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License version 2 as published by the Free Software Foundation.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
       Boston, MA  02110-1301, USA.

SEE ALSO

       xmltv(5).