TV_IMDB(1p)

💖 TV_IMDB 💖

okay bestie, so this is a User Contributed Perl Documentation page for tv_imdb, and it's about to become your whole personality, no cap. it's a Perl script that goes and gets imdb.com data and sprinkles it into your XMLTV listings files. we're gonna get into it. 🎀

---

✨ NAME ✨

tv_imdb — augment XMLTV listings files with imdb.com data. that's it, that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

tv_imdb --imdbdir <dir> [--help] [--quiet] [--download]
       [--movies-only] [--filesort] [--nosystemsort]
       [--prepStage (1-9,all)]

tv_imdb --imdbdir <dir> [--help] [--quiet]
       [--with-keywords] [--with-plot]
       [--movies-only] [--actors NUMBER]
       [--stats] [--debug]
       [--output FILE] [FILE...]

tv_imdb --imdbdir <dir>
        --validate-title 'movie title'
        --validate-year 2004
        [--with-keywords] [--with-plot]
        [--debug]

three whole moods, pick your fighter. 🫶

---

🦋 DESCRIPTION 🦋

tv_imdb is literally the twin sister of tv_cat when it comes to semantics (go read tv_cat), except — and this is the iconic part — whenever a programme shows up with a "date" entry, the title and date get used to look up extra data via XMLTV::IMDB. it's giving glow-up. ✨

• --output FILE — write to FILE instead of standard output. slay.
• --with-keywords — include IMDb keywords in the output file.
• --with-plot — include IMDb plot summary in the output file.
• --actors NUMBER — number of actors from IMDb to add (default=3).
• --quiet — disable all status messages (the ones that normally appear on stderr). shhh. 🤫
• --download — try to download data files if they are missing (in --prepStage).
• --stats — output grab stats (stats output disabled in --quiet mode).
• --debug — output info from movie matching.
• --movies-only — only augment programs that look like movie listings (4 digit 'date' field).

every single program gets checked against imdb.com data (unless --movies-only is used, then it's a much more exclusive guest list).

so for the purposes of tv_imdb, an "exact" match is defined as a case insensitive match against imdb.com data (which may or may not include the transformation of '&' to 'and' and vice-versa). the chaos is canon. 💀

if the program includes a 4 digit 'date' field, these matches get attempted, and the first successful match wins, periodt:

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

unless --movies-only is used, if the program does not include a 4 digit 'date' field, these matches are attempted, and the first succeeding match is used:

1. an "exact" title match against tv series (and tv mini series)

when a match is found in the imdb.com data, here's the whole makeover that gets applied:

1. the 'title' field is set to match exactly the title from the imdb.com 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 imdb.com 4 digit year of production.
3. the type of match found (Movie, TV Movie, Video Movie, TV Series, or TV Mini Series) is placed in the 'categories' field.
4. the url to the www.imdb.com page is added
5. the director is added if the match was a movie or if only one director is listed in the imdb.com data (because some tv series have > 30 directors — imagine 💀)
6. the top 3 billing actors are added (use -actors [num] to adjust).
7. genres added to 'categories' field (current list of genres are Short, Drama, Comedy, Documentary, Animation, Adult, Action, Family, Romance, Crime, Thriller, Musical, Adventure, Western, Horror, Sci-Fi, Fantasy, Mystery, War, Film-Noir, Music
8. imdb user ratings added to 'star-ratings' field.
9. imdb keywords added to 'keyword' fields (if --with-keywords used).
10. imdb plot summary is added (if --with-plot used).

---

🧚 HOWTO 🧚

so like, in order to actually use tv_imdb, you need:

1. choose a directory location to use for the tv_imdb database (you'll need about 1 GB of free space — she's hungry 👑)

2a. run 'tv_imdb --imdbdir <dir> --prepStage all --download' to download the list files from imdb.com. or,

2b. if you have a slow network connection you may prefer to omit the '--download' flag and be prompted for what you need to download by hand. see <http://www.imdb.com/interfaces> for the download sites. then once you have the files, rerun without '--download'.

note: '--prepStage' requires up to 520MB of memory. this can be reduced a little by running each prepStage separately, using --prepStage with each of the stages individually (see --help for details). memory use can be reduced further by using --filesort option when building the database. this will try to use the operating system to sort the interim data files rather than sorting in memory. if this system sort does not work for you then you can use the File::Sort package if it is installed on your system, by also adding the option --nosystemsort (however this method of sorting is very slow 😭). if you specify neither option then Perl will sort the files in memory.

if you are only interested in movies, you can reduce the memory required and the size of the database by passing the --movies-only option to the database build, which will exclude tv-series from the database.

3. once you have the database loaded, try 'cat tv.xml | tv_imdb --imdbdir <dir> > tv1.xml'.

feel free to report any problems with these steps at https://github.com/XMLTV/xmltv/issues. we're all friends here 🫶

---

⭐ TESTING ⭐

the --validate-title and --validate-year flags can be used to validate the information in the tv_imdb database. for exmple:

tv_imdb --imdbdir . --validate-title 'Army of Darkness' --validate-year 1994

(yes, "exmple" — we keep the typo, it's part of the lore 💖)

---

💀 BUGS 💀

could use a --configure step just like the grabbers so you do not have to specify the --imdbdir on the command line every time. also this could step you through the prep stages with more description of what is being done and what is required. Configure could also control the number of actors to add (since some movies have an awful lot), currently we are adding the top 3.

how and what to look up needs to be option driven.

needs some more controls for fine tuning "close" matches. for instance, currently it looks like the North America grabber only has date entries for movies, but the imdb.com data contains made for video movies as well as as real movies, so it's possible to get the wrong data to be inserted. in this case we may want to say "ignore tv series" and "ignore tv mini series". along with this, we'd want to define what a "close" match is. for instance does a movie by the same title with a date out by 1 year or 2 years considered a match (currently we're using 2).

nice to haves include: verification/addition of programme MPAA/VCHIP ratings, addition of imdb.com user ratings (by votes) to programmes. potentially we could expand to include "country of origin", "description", "writer" and "producer" credits, maybe even "commentator".

heh, if the XMLTV.dtd supported it, we could even include urls to head shots of the actors :)

---

🌈 SEE ALSO 🌈

xmltv(5)

---

👑 AUTHOR 👑

Jerry Veldhuis, jerry@matilda.com

---

and that's the whole thing bestie, we ate and left absolutely no crumbs ✨ this was TV_IMDB(1p), from perl v5.40.1, dated 2025-04-19 — go forth and augment those listings, main character 💅🦋🎀