2
tv_grab_na_dd - Grab TV listings for North America using Schedules
3
Direct http://www.schedulesdirect.org
8
tv_grab_na_dd --version
10
tv_grab_na_dd --capabilities
12
tv_grab_na_dd --configure [--config-file FILE] [--dd-data FILE]
13
[--reprocess] [--auto-config add|ignore]
16
tv_grab_na_dd --list-lineups [--config-file FILE] [--dd-data FILE]
19
tv_grab_na_dd [--config-file FILE] [--dd-data FILE]
20
[--reprocess] [--auto-config add|ignore]
21
[--days N] [--offset N] [--quiet] [--notrim]
22
[--old-chan-id] [--low-mem] [--output FILE]
23
[--list-channel] [--share SHAREDIR] [--list-times]
24
[--download-only] [--padd n] [--dropbadchar]
27
This script downloads TV listings using Schedules Direct's data service,
28
converts it to XMLTV format, and outputs the results.
30
You must first register with Schedules Direct at:
31
<http://www.schedulesdirect.org>
33
Schedules Direct is a non-profit organization whose mission is to
34
provide low-cost television program guide data to end-users of Open
35
Source and Freeware applications.
37
The raw data source is Tribune Media Service's Data Direct Service,
38
which is very similar to the free Zap2IT Labs service Tribune previously
41
While the service is not available for free, Schedules Direct strives to
42
keep costs as low as possible.
44
First you must become a member at the <http://www.schedulesdirect.org>
47
Next, you use that website to add lineup(s) to your account.
49
Next, you execute "tv_grab_na_dd --configure" to set up the grabber.
51
Finally, you execute tv_grab_na_dd with no arguments and it will output
52
listings in XML format to standard output. See below for other options.
56
Print a help message and exit.
59
Show the version of the grabber.
62
Show which capabilities the grabber supports. For more information,
63
see <http://xmltv.org/wiki/xmltvcapabilities.html>
65
Mode selection (default is grab mode)
67
Activates configure mode. If a config file already exists the values
71
Use this option to enable a graphical interface to be used. OPTION
72
may be 'Tk', or left blank for the best available choice. Additional
73
allowed values of OPTION are 'Term' for normal terminal output
74
(default) and 'TermNoProgressBar' to disable the use of
78
Lists available lineups. Only requires username in the config file.
79
Used by programs that automate the "--configure" process.
83
Set the name of the configuration file, the default is
84
~/.xmltv/tv_grab_na_dd.conf. This is the file created during
88
Store raw Data Direct data to this file. (default is a temporary
92
Don't get data from Data Direct, but reprocess a file saved with
95
--auto-config *add|ignore*
96
When used in --configure mode, updates the config file, removing old
97
channels, and adding or ignoring new channels. Prompts are skipped
98
if defaults are available in the current config file.
100
When used in grab mode, appends new channels to the config file.
104
Grab *n* days. The default is 7.
107
Start N days after the default.
110
Suppress some messages normally written to standard error.
113
Data Direct includes shows in progress at the start time. The
114
default behavior is to filter these shows out so data can be cleanly
115
split between days. This option turns off that filter so you get
116
shows in progress a tthe start time.
119
Use a channel id similar to the one used by the old tv_grab_na
123
Omit all but the most basic program information. Reduces memory
127
Write xml to *file* rather than standard output.
133
tv_grab_na_icons stores icons in *SHAREDIR*/icons. The share
134
directory is set at install time, but there may be times when it
135
needs to be specified. (for example: no write access to the default
139
Report to STDERR the Schedules Direct blockedTime (not currently
140
enforced) and suggestedTime values to assist automated processes
144
Don't generate any output, just fetch the data. Personally I don't
145
see the point, but it was requested and easy to add.
148
Add <n> spaces to the front of the start date. This is normally not
149
needed, but can be helpful in working around a Tribune problem when
150
the request packet spans TCP packets. Recommended initial value is
151
"20". This is only needed if you get "invalid start time" messages.
152
If this helps, please post results to the list.
155
DD data is supposed to be in UTF-8 format. Sometimes DD sends bad
156
characters which cause a "Bad XML from DD" error. This option causes
157
those bad characters to be deleted.
159
Automating configuration
160
Sometimes applications want to call tv_grab_na_dd as a standalone
161
application, but automate the configure process. The best way is to hook
162
in to the XMLTV::Ask module, but if that's not available, here is a
165
Step1. Application creates config file with username (and optionally
168
Step2. "tv_grab_na_dd --dd-data lineups.xml --list-lineups"
170
Step3. Application adds desired lineup to config file.
172
Step4. "tv_grab_na_dd --dd-data lineups.xml --reprocess
173
--auto-config add --list-channels"
175
Step5. Application edits config file as needed, and deletes
179
Data Direct offers a "suggested download time" that can be retrieved
180
with the "--list-times" option. Its use is encouraged.
182
Handling Multiple Linups
183
tv_grab_na_dd only outputs a single lineup. If your Schedules Direct
184
account has multiple lineups, they are all downloaded even though only
187
To process multiple lineups, use separate --config-file. Separate config
188
files are also handy if you need different channel sets for a lineup
189
(common with MythTV). To prevent re-downloading the data on subsequent
190
passes, the "--reprocess" option is recommended.
192
Here's an example: (the = sign is optional, but helps readability)
194
tv_grab_na_dd --config-file=lineup1.dat --output=lineup1.xml --dd-data=dd.xml
195
tv_grab_na_dd --config-file=lineup2.dat --output=lineup2.xml --dd-data=dd.xml --reprocess
196
tv_grab_na_dd --config-file=lineup3.dat --output=lineup3.xml --dd-data=dd.xml --reprocess
198
Each config file specifies the desired lineup and channel list.
200
If you want to merge the lineups into a single file, you can use tv_cat
202
tv_cat lineup1.xml lineup2.xml lineup3.xml >guide.xml
204
Non-US/Canada listings. "fake" postal codes.
205
TMS's Data direct service proivdes listings for a few non US/Canada
206
locations. These are accessed with "fake" postal codes. The following
209
147BERM Bermuda Cablevision
210
366HAMI Hamilton, Bermuda Wow World on Wireless
211
101VENE DirecTV Latin America
214
512TRIN Trinidad Express
215
782YOKO Yokota AFB, Japan. Americable International
217
For a more complete list, check the Schedules Direct FAQ
219
Adding icon links to listings
220
tv_grab_na_dd checks for channel icons in a directory *share*/icons. The
221
*share* directory is usually set during the install. For windows exe
222
users, it defaults to the location where xmltv.exe is. tv_grab_na_icons
223
is available to download the icons.
225
Notes on channel lists
226
Channel lists can be configured both at the Schedules Direct website and
227
through the grabber. This is done to allow multiple config files with
228
different channel lists as Schedules Direct only supports a single
229
channel map per lineup.
231
Similarly, tv_grab_na_dd only supports a single channel mapping for a
232
station. If multiple mappings are detected, only the first one is used
233
and you are advised to adjust your Schedules Direct lineup.
235
Notes on episode numbers
236
Three episode-num formats are supplied (when available)
239
always "..a/b" for part "a" of "b". First two xmltv_ns fields always
243
TMS generated "a.b.c/d" where "a" is a unique program id, "b" is a
244
unique episode id, "c/d" is part "c" of "d" similar to xmltv_ns.
247
Distributor-designated number corresponding to an episode of a
248
specific show. Varies by distributor.
251
If a password is stored in the config file, the config file should be
252
properly protected. Instead of storing the password in the config file,
253
it can be omitted, and will be prompted for.
255
Notes on lineup changes
256
Data Direct currently adds a channel to your lineup automatically when
257
it is available. When tv_grab_na_dd sees the new channel in the
258
Schedules Direct lineup, it prints a message (and potentially adds or
259
ignores it based on --auto-config).
261
If you are sensitive to bandwidth issues, I would set --auto-config
262
ignore and periodically check your --config-file for ignored channels
263
and remove from your Schedules Direct lineup.
265
Notes on previously-shown
266
Previous releases of tv_grab_na_dd set XMLTV's "date" field for DD
267
"original-air-date" field. The correct place for the data is
268
"previously-shown->start" The OAD is in both places temporarily for
269
compatability reasons.
271
DD has dropped the "repeat" flag and replaced it with a "new" flag. Now
272
we set "previously-shown
281
Author/Maintainer: Robert Eden, rmeden@yahoo.com
284
Ed Avis, ed@membled.com
286
Don Huettl, drh@huettl.net
288
Matti Airas, mairas@iki.fi (I used tv_grab_fi as a template)
290
and of course everyone else I forgot to mention. :)
2
tv_grab_na_dd - Grab TV listings for North America using Schedules
3
Direct http://www.schedulesdirect.org
8
tv_grab_na_dd --version
10
tv_grab_na_dd --capabilities
12
tv_grab_na_dd --configure [--config-file FILE] [--dd-data FILE]
13
[--reprocess] [--auto-config add|ignore]
16
tv_grab_na_dd --list-lineups [--config-file FILE] [--dd-data FILE]
19
tv_grab_na_dd [--config-file FILE] [--dd-data FILE]
20
[--reprocess] [--auto-config add|ignore]
21
[--days N] [--offset N] [--quiet] [--notrim]
22
[--old-chan-id] [--low-mem] [--output FILE]
23
[--list-channel] [--share SHAREDIR] [--list-times]
24
[--download-only] [--padd n] [--dropbadchar] [--agent NAME]
27
This script downloads TV listings using Schedules Direct's data service,
28
converts it to XMLTV format, and outputs the results.
30
You must first register with Schedules Direct at:
31
<http://www.schedulesdirect.org>
33
Schedules Direct is a non-profit organization whose mission is to
34
provide low-cost television program guide data to end-users of Open
35
Source and Freeware applications.
37
The raw data source is Tribune Media Service's Data Direct Service,
38
which is very similar to the free Zap2IT Labs service Tribune previously
41
While the service is not available for free, Schedules Direct strives to
42
keep costs as low as possible.
44
First you must become a member at the <http://www.schedulesdirect.org>
47
Next, you use that website to add lineup(s) to your account.
49
Next, you execute "tv_grab_na_dd --configure" to set up the grabber.
51
Finally, you execute tv_grab_na_dd with no arguments and it will output
52
listings in XML format to standard output. See below for other options.
56
Print a help message and exit.
59
Show the version of the grabber.
62
Show which capabilities the grabber supports. For more information,
63
see <http://xmltv.org/wiki/xmltvcapabilities.html>
65
Mode selection (default is grab mode)
67
Activates configure mode. If a config file already exists the values
71
Use this option to enable a graphical interface to be used. OPTION
72
may be 'Tk', or left blank for the best available choice. Additional
73
allowed values of OPTION are 'Term' for normal terminal output
74
(default) and 'TermNoProgressBar' to disable the use of
78
Lists available lineups. Only requires username in the config file.
79
Used by programs that automate the "--configure" process.
83
Set the name of the configuration file, the default is
84
~/.xmltv/tv_grab_na_dd.conf. This is the file created during
88
Store raw Data Direct data to this file. (default is a temporary
92
Don't get data from Data Direct, but reprocess a file saved with
95
--auto-config *add|ignore*
96
When used in --configure mode, updates the config file, removing old
97
channels, and adding or ignoring new channels. Prompts are skipped
98
if defaults are available in the current config file.
100
When used in grab mode, appends new channels to the config file.
104
Grab *n* days. The default is 7.
107
Start N days after the default.
110
Suppress some messages normally written to standard error.
113
Data Direct includes shows in progress at the start time. The
114
default behavior is to filter these shows out so data can be cleanly
115
split between days. This option turns off that filter so you get
116
shows in progress a tthe start time.
119
Use a channel id similar to the one used by the old tv_grab_na
123
Omit all but the most basic program information. Reduces memory
127
Write xml to *file* rather than standard output.
133
tv_grab_na_icons stores icons in *SHAREDIR*/icons. The share
134
directory is set at install time, but there may be times when it
135
needs to be specified. (for example: no write access to the default
139
Report to STDERR the Schedules Direct blockedTime (not currently
140
enforced) and suggestedTime values to assist automated processes
144
Don't generate any output, just fetch the data. Personally I don't
145
see the point, but it was requested and easy to add.
148
Add <n> spaces to the front of the start date. This is normally not
149
needed, but can be helpful in working around a Tribune problem when
150
the request packet spans TCP packets. Recommended initial value is
151
"20". This is only needed if you get "invalid start time" messages.
152
If this helps, please post results to the list.
155
DD data is supposed to be in UTF-8 format. Sometimes DD sends bad
156
characters which cause a "Bad XML from DD" error. This option causes
157
those bad characters to be deleted.
160
appends NAME to the http agent string when fetching data. This is a
161
polite way to tell Schedules Direct which application is being used.
162
It helps developers know how many people are using their application
163
and gives applications credit towards free accounts.
165
Automating configuration
166
Sometimes applications want to call tv_grab_na_dd as a standalone
167
application, but automate the configure process. The best way is to hook
168
in to the XMLTV::Ask module, but if that's not available, here is a
171
Step1. Application creates config file with username (and optionally
174
Step2. "tv_grab_na_dd --dd-data lineups.xml --list-lineups"
176
Step3. Application adds desired lineup to config file.
178
Step4. "tv_grab_na_dd --dd-data lineups.xml --reprocess
179
--auto-config add --list-channels"
181
Step5. Application edits config file as needed, and deletes
185
Data Direct offers a "suggested download time" that can be retrieved
186
with the "--list-times" option. Its use is encouraged.
188
Handling Multiple Linups
189
tv_grab_na_dd only outputs a single lineup. If your Schedules Direct
190
account has multiple lineups, they are all downloaded even though only
193
To process multiple lineups, use separate --config-file. Separate config
194
files are also handy if you need different channel sets for a lineup
195
(common with MythTV). To prevent re-downloading the data on subsequent
196
passes, the "--reprocess" option is recommended.
198
Here's an example: (the = sign is optional, but helps readability)
200
tv_grab_na_dd --config-file=lineup1.dat --output=lineup1.xml --dd-data=dd.xml
201
tv_grab_na_dd --config-file=lineup2.dat --output=lineup2.xml --dd-data=dd.xml --reprocess
202
tv_grab_na_dd --config-file=lineup3.dat --output=lineup3.xml --dd-data=dd.xml --reprocess
204
Each config file specifies the desired lineup and channel list.
206
If you want to merge the lineups into a single file, you can use tv_cat
208
tv_cat lineup1.xml lineup2.xml lineup3.xml >guide.xml
210
Non-US/Canada listings. "fake" postal codes.
211
TMS's Data direct service proivdes listings for a few non US/Canada
212
locations. These are accessed with "fake" postal codes. The following
215
147BERM Bermuda Cablevision
216
366HAMI Hamilton, Bermuda Wow World on Wireless
217
101VENE DirecTV Latin America
220
512TRIN Trinidad Express
221
782YOKO Yokota AFB, Japan. Americable International
223
For a more complete list, check the Schedules Direct FAQ
225
Adding icon links to listings
226
tv_grab_na_dd checks for channel icons in a directory *share*/icons. The
227
*share* directory is usually set during the install. For windows exe
228
users, it defaults to the location where xmltv.exe is. tv_grab_na_icons
229
is available to download the icons.
231
Notes on channel lists
232
Channel lists can be configured both at the Schedules Direct website and
233
through the grabber. This is done to allow multiple config files with
234
different channel lists as Schedules Direct only supports a single
235
channel map per lineup.
237
Similarly, tv_grab_na_dd only supports a single channel mapping for a
238
station. If multiple mappings are detected, only the first one is used
239
and you are advised to adjust your Schedules Direct lineup.
241
Notes on episode numbers
242
Three episode-num formats are supplied (when available)
245
always "..a/b" for part "a" of "b". First two xmltv_ns fields always
249
TMS generated "a.b.c/d" where "a" is a unique program id, "b" is a
250
unique episode id, "c/d" is part "c" of "d" similar to xmltv_ns.
253
Distributor-designated number corresponding to an episode of a
254
specific show. Varies by distributor.
257
If a password is stored in the config file, the config file should be
258
properly protected. Instead of storing the password in the config file,
259
it can be omitted, and will be prompted for.
261
Notes on lineup changes
262
Data Direct currently adds a channel to your lineup automatically when
263
it is available. When tv_grab_na_dd sees the new channel in the
264
Schedules Direct lineup, it prints a message (and potentially adds or
265
ignores it based on --auto-config).
267
If you are sensitive to bandwidth issues, I would set --auto-config
268
ignore and periodically check your --config-file for ignored channels
269
and remove from your Schedules Direct lineup.
271
Notes on previously-shown
272
Previous releases of tv_grab_na_dd set XMLTV's "date" field for DD
273
"original-air-date" field. The correct place for the data is
274
"previously-shown->start" The OAD is in both places temporarily for
275
compatability reasons.
277
DD has dropped the "repeat" flag and replaced it with a "new" flag. Now
278
we set "previously-shown
287
Author/Maintainer: Robert Eden, rmeden@yahoo.com
290
Ed Avis, ed@membled.com
292
Don Huettl, drh@huettl.net
294
Matti Airas, mairas@iki.fi (I used tv_grab_fi as a template)
296
and of course everyone else I forgot to mention. :)
added
removed
xmltv/doc/man/tv_grab_na_dd.txt
