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

FreeBSD Manual Pages


home | help
TV_GRAB_NA_DD(1)      User Contributed Perl Documentation     TV_GRAB_NA_DD(1)

       tv_grab_na_dd - Grab TV listings	for North America using	Schedules

	   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]

	   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]

       This script downloads TV	listings using Schedules Direct's data
       service,	converts it to XMLTV format, and outputs the results.

       You must	first register with Schedules Direct at:

       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.

       The raw data source is Schedules	Direct's SD-DD service,	which
       purchases Data from Gracenote (formerly known as	Tribune	Media

       While the service is not	available for free, Schedules Direct strives
       to keep costs as	low as possible.

       First you must become a member at the <>

       Next, you use that website to add lineup(s) to your account.

       Next, you execute "tv_grab_na_dd	--configure" to	set up the grabber.

       Finally,	you execute tv_grab_na_dd with no arguments and	it will	output
       listings	in XML format to standard output.  See below for other

       Like many utilities, tv_grab_na_dd tries	to exit	with a "0" on success
       and something else on error.

Stand-alone options
	   Print a help	message	and exit.

	   Show	the version of the grabber.

	   Show	which capabilities the grabber supports. For more information,
	   see <>

Mode selection (default	is grab	mode)
	   Activates configure mode.  If a config file already exists the
	   values are used as defaults.

       --gui OPTION
	   Use this option to enable a graphical interface to be used.	OPTION
	   may be 'Tk',	or left	blank for the best available choice.
	   Additional allowed values of	OPTION are 'Term' for normal terminal
	   output (default) and	'TermNoProgressBar' to disable the use of

	   Lists available lineups.  Only requires username in the config
	   file. Used by programs that automate	the "--configure" process.

General	Options
       --config-file file
	   Set the name	of the configuration file, the default is
	   ~/.xmltv/tv_grab_na_dd.conf.	 This is the file created during
	   "--configure" mode.

       --dd-data file
	   Store raw Data Direct data to this file. (default is	a temporary

	   Don't get data from Data Direct, but	reprocess a file saved with

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

	   When	used in	grab mode, appends new channels	to the config file.

Grabber	Mode options
       --days n
	   Grab	n days.	 The default is	7.

       --offset	n
	   Start N days	after the default.

	   Suppress some messages normally written to standard error.

	   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.

	   Use a channel id similar to the one used by the old tv_grab_na

	   Omit	all but	the most basic program information. Reduces memory

       --output	file
	   Write xml to	file rather than standard output.

	   Same	as --days 0

       --share SHAREDIR
	   tv_grab_na_icons stores icons in SHAREDIR/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)

	   Report to STDERR the	Schedules Direct blockedTime (not currently
	   enforced) and suggestedTime values to assist	automated processes
	   with	scheduling.

	   Don't generate any output, just fetch the data.  Personally I don't
	   see the point, but it was requested and easy	to add.

       --padd n
	   Add <n> 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 TCP packets.  Recommended initial
	   value is "20".  This	is only	needed if you get "invalid start time"
	   messages.  If this helps, please post results to the	list.

	   DD data is supposed to be in	UTF-8 format.  Sometimes DD sends bad
	   characters which cause a "Bad XML from DD" error.  This option
	   causes those	bad characters to be deleted.

       --agent NAME
	   appends NAME	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.

Automating configuration
       Sometimes applications want to call tv_grab_na_dd 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.

	   Step1. Application creates config file with username	(and
	   optionally password).

	   Step2. "tv_grab_na_dd --dd-data lineups.xml --list-lineups"

	   Step3. Application adds desired lineup to config file.

	   Step4. "tv_grab_na_dd --dd-data lineups.xml --reprocess
	   --auto-config add --list-channels"

	   Step5. Application edits config file	as needed, and deletes

Grabber	Timing
       Data Direct offers a "suggested download	time" that can be retrieved
       with the	"--list-times" option. Its use is encouraged.

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.

       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 "--reprocess" option is recommended.

       Here's an example: (the = sign is optional, but helps readability)

	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

       Each config file	specifies the desired lineup and channel list.

       If you want to merge the	lineups	into a single file, you	can use	tv_cat

	tv_cat lineup1.xml lineup2.xml lineup3.xml >guide.xml

Adding icon links to listings
       tv_grab_na_dd checks for	channel	icons in a directory share/icons.  The
       share directory is usually set during the install.  For windows exe
       users, it defaults to the location where	xmltv.exe is.
       tv_grab_na_icons	is available to	download the icons.

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.

       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.

Notes on episode numbers
       Three episode-num formats are supplied (when available)

	   always "..a/b" for part "a" of "b". First two xmltv_ns fields
	   always blank.

	   Gracenote generated "a.b.c/d" where "a" is a	unique program id, "b"
	   is a	unique episode id, "c/d" is part "c" of	"d" similar to

	   Distributor-designated number corresponding to an episode of	a
	   specific show. Varies by distributor.

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.

Notes on lineup	changes
       Data Direct currently adds a channel to your lineup automatically when
       it is available.	 When tv_grab_na_dd sees the new channel in the
       Schedules Direct	lineup,	it prints a message (and potentially adds or
       ignores it based	on --auto-config).

       If you are sensitive to bandwidth issues, I would set --auto-config
       ignore and periodically check your --config-file	for ignored channels
       and remove from your Schedules Direct lineup.

Notes on previously-shown
       Previous	releases of tv_grab_na_dd set XMLTV's "date" field for DD
       "original-air-date" field.  The correct place for the data is
       "previously-shown->start"  The OAD is in	both places temporarily	for
       compatibility reasons.

       DD has dropped the "repeat" flag	and replaced it	with a "new" flag. Now
       we set "previously-shown

Known issues


       Author/Maintainer: Robert Eden,

	   Ed Avis,

	   Don Huettl,

	   Matti Airas, (I used tv_grab_fi as a template)

	   and of course everyone else I forgot	to mention. :)

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

NAME | SYNOPSIS | DESCRIPTION | Stand-alone options | Mode selection (default is grab mode) | General Options | Grabber Mode options | Automating configuration | Grabber Timing | Handling Multiple Linups | Adding icon links to listings | Notes on channel lists | Notes on episode numbers | Notes on passwords | Notes on lineup changes | Notes on previously-shown | Known issues | SEE ALSO | Author

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

home | help