TV_GRAB..._SQLITE(1p)

📦
version 1.4.0 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 tv_grab_zz_sdjson_sqlite — bestie edition

okay so this is from the User Contributed Perl Documentation crew, section 1p, and it's literally the whole manual for tv_grab_zz_sdjson_sqlite. grab a snack, we're doing this 🍓

✨ NAME ✨

tv_grab_zz_sdjson_sqlite — grab TV and radio program listings from Schedules Direct (subscription required). yes bestie, subscription. we don't make the rules 💅

🌸 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] [--resturl URL] [--routeto ROUTETO]

tv_grab_zz_sdjson_sqlite --configure [--config-file FILE]
              [--quiet] [--debug]
              [--passwordhash HASH] [--resturl URL] [--routeto ROUTETO]

tv_grab_zz_sdjson_sqlite --list-channels [--config-file FILE]
              [--output FILE] [--quiet] [--debug]
              [--passwordhash HASH] [--resturl URL] [--routeto ROUTETO]

tv_grab_zz_sdjson_sqlite --list-lineups  [--config-file FILE]
              [--output FILE] [--quiet] [--debug]
              [--passwordhash HASH] [--resturl URL] [--routeto ROUTETO]

tv_grab_zz_sdjson_sqlite --get-lineup [--config-file FILE]
              [--output FILE] [--quiet] [--debug]
              [--passwordhash HASH] [--resturl URL] [--routeto ROUTETO]

🦋 DESCRIPTION 🦋

So the tea is: this thing spits out TV listings in XMLTV format for so many locations across North America (US/CA) plus some other selected countries internationally. 🌎

Where does the data come from? <http://www.schedulesdirect.org> bestie. and you must make an account on the Schedules Direct site to grab anything. the signup requirements and the list of supported locations? go read the Schedules Direct site, that's where that lives. 👑

Here's the slay part: this grabber uses a shared local database, which means it only downloads the new/changed/updated info. and if you've got a messy mix of OTA, Cable, and/or Satellite providers, it can substantially reduce the download times — because some data (like schedules and program details) is commonly shared between sources in the same location. shared data, shared vibes, less waiting ✨

okay so the order of operations, and I need you to hear me on this:

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 shares the downloaded information across multiple lineups, and can substantially reduce the royal overheads in those cases 👑)

💅 OPTIONS 💅

  • --manage-lineups — do the Schedules Direct lineup management stuff (adding/deleting lineups from your account, and creating the local EPG database). You can manage lineups without a configuration file (it'll just prompt you for what it needs), but if a config file exists, it'll be used to grab initial credentials. 🫶 and listen: if you change your password at Schedules Direct, you'll need to update the database (or display the new password hash) using --manage-lineups. don't skip that step, she's important.
  • --configure — prompts you for which lineup to download and writes the configuration file. heads up though: you have to run --manage-lineups first to create and initialize the database and configure lineups. no shortcuts bestie.
  • --config-file FILE — set the name of the configuration file. default is ~/.xmltv/tv_grab_zz_sdjson_sqlite.conf. this is the file that --configure writes and that gets read when grabbing. 💾
  • --output FILE — when grabbing, write output to FILE instead of standard output.
  • --download-only — just do a download of the data, no output. pure data acquisition energy.
  • --no-download — don't download anything, just use whatever's already in the local database. since the code optimizes what it downloads, this is nominally useful only in offline situations. 🛜
  • --force-download — deletes most of the existing local database data and forces a full download. if you suspect the data is corrupt (and it's not being automatically corrected), forcing a new download might be necessary. nuclear option, but sometimes you gotta 🔥
  • --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. shhh 🤫
  • --debug — more info on progress to stderr, to help with debugging. it can get very verbose, but too much data is better than not enough if errors need to be squashed. ⚠️ note that the debug data may contain information you might prefer to be confidential — like your password hash — so treat the output appropriately. fr fr, be careful with that.
  • --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 when directed by Schedules Direct staff. 🧪
  • --routeto ROUTETO — provide the Schedules Direct service endpoint RouteTo header. also primarily useful for testing when directed by Schedules Direct staff. 🧪
  • --list-channels — write output giving <channel> elements for every channel available in the current configuration.
  • --list-lineups — write output giving a list of available viewing regions. ⚠️ note that list-lineups is not fully standardized, so the output is subject to change. she's a little unhinged and we love her for it.
  • --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. same chaotic energy.
  • --capabilities — show which capabilities the grabber supports. for more info, 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'll 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. 🧹 so tidy, so iconic.

🌈 USAGE 🌈

All the normal XMLTV capabilities are included. 💯

Note that Schedules Direct only has data for a maximum of about 21 days (although it may be less for some channels) — but the accuracy of the data at the end of the period tends to be poor. so like, the last few days are giving "trust me bro" energy. 😭

💀 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. she tries again, that's called resilience bestie 💅

🧚 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. no spaces, we don't do spaces there. 🙈

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
  • 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. so like, a situationship with the fixups, not a marriage. ⏳

👑 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. 📞 not us, them, okay?

⭐ 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. 💖 we ignore it. it's fine. it's giving dramatic for no reason.

🔥 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 a 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 understandably be a challenge, and the lineup proposals to extend the capability to provide a mechanism to support "channels" has not progressed in years. so it's just... like that. 🤷

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. 😭 the struggle is real and it is structural.

🎀 CHANNEL SELECTION 🎀

okay bestie, listen up, because this part is lowkey the messiest bit and I need you to stay with me 💖

Because of how XMLTV interprets <channel>, this grabber does its own lil thing and implements its own "channel" (transport) selection mechanism — and yes, it parallels the one on the Schedules Direct site, so if you've seen it there you're already halfway home 🫶. It lives inside the --manage-lineups capability. The grabber defaults will result in all channels and stations associated with the lineup being written. Periodt. ✨

In some cases though, some people may want to limit the channels to a small subset of everything available. The most common scenario? A Cable or Satellite service that has billions and billions of channels, but you're only subscribed to a significantly reduced programming tier, and your application doesn't have the ability to restrict the display/access to that huge number of channels 😭. So this exists to help.

There is just enough flexibility to allow one to confuse oneself some of the time. That's the vibe. That's the whole design philosophy fr fr 💀

⚠️ Note: 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. So yeah, that can happen.

The lineup channel selection default can also be set for an existing lineup. But — and I'm saying this with love — due to the potential of future surprises or confusion, if one can avoid using the channel selection capability, one is likely better off. 👑 That's the advice. Take it or leave it.

🌸 FAQs 🌸

No FAQs yet.... 🙈

(iconic of them honestly, but that's the whole FAQ section. we move.)

💀 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. No cap, go read their stuff before you 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 (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).

and that's a wrap bestie!! 💖 the whole thing is perl v5.40.1, dated 2025-04-19, and it's the user contributed perl documentation version of TV_GRAB..._SQLITE(1p) — go grab your listings, you absolute icon 🌈⭐🎀

📦 where this page comes from