Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

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

       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]

       Output TV listings in XMLTV format for many locations available in
       North America (US/CA) 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.

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

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

       --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 currupt
       (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

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

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

       --version Show the version of the grabber.

       --help Print a help message and exit.

       --info Print a help page	and exit.

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

       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.

       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.

       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

       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

       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.

       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.

       tv_validate_grabber may report an error similar to:

	     "Line 123 Duplicate channel-tag for ''"

       This is a 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 (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.

       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.

       No FAQs yet....

       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.

       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 (c) 2016, 2017	Gary Buhrmaster	<>

       This code is distributed	under the GNU General Public License v2

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


perl v5.32.0			  2020-08-27	   TV_GRAB_ZZ_SDJSON_SQLITE(1)


Want to link to this manual page? Use this URL:

home | help