.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TV_IMDB 1p"
.TH TV_IMDB 1p "2023-02-24" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
tv_imdb \- Augment XMLTV listings files with imdb.com data.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
tv_imdb \-\-imdbdir
[\-\-help] [\-\-quiet] [\-\-download]
[\-\-movies\-only] [\-\-filesort] [\-\-nosystemsort]
[\-\-prepStage (1\-9,all)]
.PP
tv_imdb \-\-imdbdir [\-\-help] [\-\-quiet]
[\-\-with\-keywords] [\-\-with\-plot]
[\-\-movies\-only] [\-\-actors \s-1NUMBER\s0]
[\-\-stats] [\-\-debug]
[\-\-output \s-1FILE\s0] [\s-1FILE...\s0]
.PP
tv_imdb \-\-imdbdir
\-\-validate\-title 'movie title'
\-\-validate\-year 2004
[\-\-with\-keywords] [\-\-with\-plot]
[\-\-debug]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
tv_imdb is very similar to tv_cat in semantics (see tv_cat),
except whenever a programme appears with \*(L"date\*(R" entry the
title and date are used to look up extra data using \s-1XMLTV::IMDB.\s0
.PP
\&\fB\-\-output \s-1FILE\s0\fR write to \s-1FILE\s0 rather than standard output.
.PP
\&\fB\-\-with\-keywords\fR include IMDb keywords in the output file.
.PP
\&\fB\-\-with\-plot\fR include IMDb plot summary in the output file.
.PP
\&\fB\-\-actors \s-1NUMBER\s0\fR number of actors from IMDb to add (default=3).
.PP
\&\fB\-\-quiet\fR disable all status messages (that normally appear on stderr).
.PP
\&\fB\-\-download\fR try to download data files if they are missing (in \-\-prepStage).
.PP
\&\fB\-\-stats\fR output grab stats (stats output disabled in \-\-quiet mode).
.PP
\&\fB\-\-debug\fR output info from movie matching
.PP
\&\fB\-\-movies\-only\fR only augment programs that look like movie listings (4 digit
\&'date' field).
.PP
All programs are checked against imdb.com data (unless \-\-movies\-only is used).
.PP
For the purposes of tv_imdb, an \*(L"exact\*(R" 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.
.PP
If the program includes a 4 digit 'date' field the following
matches are attempted, with the first successful match being used:
.PP
\&\fB1.\fR an \*(L"exact\*(R" title/year match against movie titles is done
.PP
\&\fB2.\fR an \*(L"exact\*(R" title match against tv series (and tv mini series)
.PP
\&\fB3.\fR an \*(L"exact\*(R" title match against movie titles with production dates
within 2 years of the 'date' value.
.PP
Unless \-\-movies\-only is used, if the program does not include a 4 digit
\&'date' field the following
matches are attempted, the first succeeding match is used:
.PP
\&\fB1.\fR an \*(L"exact\*(R" title match against tv series (and tv mini series)
.PP
When a match is found in the imdb.com data the following is applied:
.PP
\&\fB1.\fR 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.
.PP
\&\fB2.\fR if the match is a movie, the 'date' field is set to imdb.com
4 digit year of production.
.PP
\&\fB3.\fR the type of match found (Movie, \s-1TV\s0 Movie, Video Movie, \s-1TV\s0 Series,
or \s-1TV\s0 Mini Series) is placed in the 'categories' field.
.PP
\&\fB4.\fR the url to the www.imdb.com page is added
.PP
\&\fB5.\fR 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)
.PP
\&\fB6.\fR the top 3 billing actors are added (use \-actors [num] to adjust).
.PP
\&\fB7.\fR 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
.PP
\&\fB8.\fR imdb user ratings added to 'star\-ratings' field.
.PP
\&\fB9.\fR imdb keywords added to 'keyword' fields (if \-\-with\-keywords used).
.PP
\&\fB10.\fR imdb plot summary is added (if \-\-with\-plot used).
.SH "HOWTO In order to use tv_imdb, you need:"
.IX Header "HOWTO In order to use tv_imdb, you need:"
\&\fB1.\fR choose a directory location to use for the tv_imdb database (you'll
need about 1 \s-1GB\s0 of free space),
.PP
\&\fB2a.\fR run 'tv_imdb \-\-imdbdir \-\-prepStage all \-\-download'
to download the list files from imdb.com. Or,
.PP
\&\fB2b\fR 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 for the download sites.
Then once you have the files rerun without '\-\-download'.
.PP
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.
.PP
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.
.PP
\&\fB3.\fR Once you have the database loaded try
\&'cat tv.xml | tv_imdb \-\-imdbdir > tv1.xml'.
.PP
Feel free to report any problems with these steps at https://github.com/XMLTV/xmltv/issues.
.SH "TESTING"
.IX Header "TESTING"
The \-\-validate\-title and \-\-validate\-year flags can be used to validate the
information in the tv_imdb database. For exmple:
.PP
.Vb 1
\& tv_imdb \-\-imdbdir . \-\-validate\-title \*(AqArmy of Darkness\*(Aq \-\-validate\-year 1994
.Ve
.SH "BUGS"
.IX Header "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.
.PP
How and what to look up needs to be option driven.
.PP
Needs some more controls for fine tuning \*(L"close\*(R" 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 \*(L"ignore tv
series\*(R" and \*(L"ignore tv mini series\*(R". Along with this, we'd want
to define what a \*(L"close\*(R" 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).
.PP
Nice to haves include: verification/addition of programme \s-1MPAA/VCHIP\s0 ratings,
addition of imdb.com user ratings (by votes) to programmes. Potentially we
could expand to include \*(L"country of origin\*(R", \*(L"description\*(R", \*(L"writer\*(R" and
\&\*(L"producer\*(R" credits, maybe even \*(L"commentator\*(R".
.PP
Heh, if the \s-1XMLTV\s0.dtd supported it, we could even include urls to head
shots of the actors :)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBxmltv\fR\|(5)
.SH "AUTHOR"
.IX Header "AUTHOR"
Jerry Veldhuis, jerry@matilda.com