TV_TMDB(1)

📦 version 1.4.0, in alpine 3.24

💖 tv_tmdb — the perl manual page, but make it group chat 💖

okay so bestie, you're looking at TV_TMDB(1), a User Contributed Perl Documentation page, and honestly? it's a banger. it's tv_tmdb, and it's here to make your XMLTV listings files pop off with data from themoviedb.org. no cap. let's get into it 🎀

✨ NAME ✨

tv_tmdb — augment XMLTV listings files with themoviedb.org data. literally that's the whole gig. 💅

🌸 SYNOPSIS 🌸

tv_tmdb
       [--help] [--quiet]
       [--configure] [--config-file FILE]
       [--apikey KEY]
       [--with-keywords] [--with-plot]
       [--movies-only] [--actors NUMBER] [--reviews NUMBER]
       [--stats] [--debug NUMBER]
       [--output FILE] [FILE...]

like, copy that verbatim bestie, don't be weird about it 🫶

🦋 PURPOSE 🦋

so tv_tmdb reads your xml file of tv programmes and tries to find a matching entry for the programme title in The Movie Database — that's the community-built movie and TV database, iykyk. 👑

access to the TMDB system goes through their API interface, and it hits the data in realtime. which means: you must be online to be able to augment your listings using tv_tmdb. offline girlies, this is not your moment 😭

using the TMDB system requires an API key, and you can get one from The Movie Database website (https://www.themoviedb.org/). the key is free for non-commercial use. free! iconic!

you will need to get this API key before you can start using tv_tmdb. no key, no vibes. that's the rule.

🎀 PARAMETERS 🎀

  • --apikey KEY — your TMDB API key. your golden ticket, your main character credential 🔑
  • --output FILE — write to FILE rather than standard output. direct your slay elsewhere 💫
  • --with-keywords — include tmdb keywords in the output file.
  • --with-plot — include tmdb plot summary in the output file. the lore!! 📖
  • --actors NUMBER — number of actors from tmdb to add (default=3).
  • --reviews NUMBER — number of reviews from tmdb to add (default=0).
  • --movies-only — only augment programs that look like movie listings (have a 4 digit date field). movie-only era 🎬
  • --quiet — disable all status messages (that normally appear on stderr). silence is golden, periodt.
  • --stats — output grab stats (stats output disabled in --quiet mode).
  • --configure — store frequent parameters in a config file (apikey, actors).
  • --config-file FILE — specify your own file location instead of XMLTV default.
  • --debug NUMBER — output info from movie matching (optional value to increase debug level: 2 is probably the max you will find useful). lowkey 2 is your ceiling, bestie, don't push it 💀

💜 DESCRIPTION 💜

all programs are checked against themoviedb.org (TMDB) data (unless --movies-only is used).

for the purposes of tv_tmdb, an "exact" match is defined as a case insensitive match against themoviedb.org data (which may or may not include the transformation of '&' to 'and' and vice-versa). the way that little & → and situation exists is so real 🙈

🌈 if the program has a 4 digit date field

the following matches are attempted, with the first successful match being used:

  1. an "exact" title/year match against movie titles is done
  2. an "exact" title match against tv series
  3. an "exact" title match against movie titles with production dates within 2 years of the date value.

⭐ unless --movies-only is used, and the program does NOT include a 4 digit date field

the following matches are attempted, and the first succeeding match is used:

  1. an "exact" title match against tv series

👑 when a match IS found

when a match is found in the themoviedb.org data, the following is applied:

  1. the 'title' field is set to match exactly the title from the themoviedb.org data. this includes modification of the case to match and any transformations mentioned above.
  2. if the match is a movie, the 'date' field is set to themoviedb.org 4 digit year of production.
  3. the type of match found (Movie, or TV Series) is placed in the 'categories' field.
  4. a url to the program on www.imdb.com is added.
  5. the director is added if the match was a movie or if only one director is listed in the themoviedb.org data (because some tv series have. 30 directors). yes, thirty. she said what she said 💀
  6. the top 3 billing actors are added (use --actors [num] to adjust).
  7. genres are added to 'categories' field.
  8. TMDB user-ratings added to 'star-ratings' field.
  9. TMDB keywords are added to 'keyword' fields (if --with-keywords used).
  10. TMDB plot summary is added (if --with-plot used).
  11. The top TMDB reviews are added (use --reviews [num] to adjust).

🧚 HOWTO 🧚

  1. in order to use tv_tmdb, you need an API key from themoviedb.org. these are free for Personal use. you need to create a log-in with themoviedb.org and then click on the API link on the Settings page. (See https://www.themoviedb.org/documentation/api )
  2. run 'tv_tmdb --apikey <key> --output myxmlout.xml myxmlin.xml' or 'cat tv.xml | tv_tmdb --apikey <key> tv1.xml' or etc.
  3. to use a config file to avoid entering your apikey on the commandline, run 'tv_tmdb --configure' and follow the prompts.

feel free to report any problems with these steps at https://github.com/XMLTV/xmltv/issues. go off, file that bug 🫶

🍓 BACKGROUND 🍓

like the original (pre Amazon) IMDb, "The Movie Database" (TMDB) (https://www.themoviedb.org/) is a community effort, and relies on people adding the movies. it's giving crowdsourced excellence.

note TMDB is not IMDB...but it's getting there! as at December 2021, TMDB has over 700,000 movies and 123,000 TV shows while IMDB has approx 770,000 movies and 217,000 TV series. however there are bound to be some films/TV programmes on IMDb which are not on TMDB. so if you can't find a film that you can find manually on IMDb then you might consider signing up to TMDB and adding it yourself. be the change you wish to see in the database 💅✨

💀 BUGS 💀

we only add movie information to programmes that have a 'date' element defined (since we need a year to work with when verifing we got the correct hit in the TMDB data).

a date is required for a movie to be augmented. (if no date is found in the incoming data then it is assumed the program is a tv series/episode.) soz, that's just how it is 😭

for movies we look for matches on title plus release-year within two years of the program date. we could check other data such as director or top 3 actors to help identify the correct match. could! but doesn't. noted 🫠

headshots of the actors are possible with the TMDB data, but the XMLTV.dtd does not currently support them. the pictures are right there and yet... 🙈

🔥 DISCLAIMER 🔥

this product uses the TMDB API but is not endorsed or certified by TMDB.

it is YOUR responsibility to comply with TMDB's Terms of Use of their API. no cap, read them.

in particular your attention is drawn to TMDB's restrictions on Commercial Use. your use is deemed to be Commercial if any of:

  1. users are charged a fee for your product or a 3rd party's product or service or a 3rd party's service that includes some sort of integration using the TMDB APIs.
  2. you sell services using TMDb's APIs to bring users' TMDB content into your service.
  3. your site is a "destination" site that uses TMDB content to drive traffic and generate revenue.
  4. your site generates revenue by charging users for access to content related to TMDB content such as movies, television shows and music.
⚠️ if any of these events are true then you cannot use TMDB data in any part of your product or service without a commercial license. that's the serious bit, bestie, don't skip it 🙏

🌟 SEE ALSO 🌟

  • xmltv(5) — go read it, it's the sibling 💖

🌸 AUTHOR 🌸

Geoff Westcott, Jerry Veldhuis — legends, honestly 👑👑

and that's the whole page, bestie! this one's flying the perl v5.42.2 banner and it's dated 2025-06-30. thanks for reading, mwah 💋🎀✨

📦 where this page comes from