Plugin Authors

For plugin authors

TMDBCockpit offers other plugins three ways to work with TMDB, all through the plugin system of Enigma2: a plugin of a special type is registered, and the caller finds it with plugins.getPlugins(where=...). The types are numbers, defined in PluginUtils.py (a file the Cockpit plugins share):

Constant	Value	Direction	What it does
WHERE_TMDB_MOVIELIST	-97	TMDBCockpit provides	Opens the TMDBCockpit screens for a recording
WHERE_TMDB_SEARCH	-98	TMDBCockpit provides	Looks up a title and returns the data, without any screen
WHERE_SEARCH	-99	TMDBCockpit calls	Lets another plugin handle the Search key (INFO) in the details screen

PluginUtils.py also has a helper that returns the first plugin of a type:

from .PluginUtils import getPlugin, WHERE_TMDB_SEARCH, WHERE_TMDB_MOVIELIST

plugin = getPlugin(WHERE_TMDB_SEARCH)   # None if TMDBCockpit is not installed

Opening the screens for a recording

plugin = getPlugin(WHERE_TMDB_MOVIELIST)
if plugin:
    plugin(session, service, callback=self.tmdbClosed)

def tmdbClosed(self, files_saved):
    if files_saved:
        ...   # description, cover or backdrop were saved next to the recording: refresh the list

• service is the eServiceReference of the recording (or of a folder). Its name, or else the name of its file or folder, is the search text (see the User Guide).
• The callback is optional. It is called when TMDBCockpit is closed, with True if it saved a file for the recording.
• The user can save the description, cover and backdrop only when TMDBCockpit is opened this way, because only then it knows where the recording is.

The standard movie list of Enigma2 finds the same function as a plugin of type PluginDescriptor.WHERE_MOVIELIST.

Looking up data without a screen

def gotData(result):
    if result:
        title = result["title"] if result["title"] != "None" else result["name"]   # a movie has a title, a series a name
        print(title, result["year"], result["rating"])
    else:
        print("nothing found")

plugin = getPlugin(WHERE_TMDB_SEARCH)
if plugin:
    plugin("Casablanca", callback=gotData)

The lookup runs on a worker thread, and the callback is called on the main thread with a dictionary, or with an empty dictionary {} if the text is empty or nothing was found. The text is cleaned like for the screens, and if there is no result it is searched again with its last word removed. The first movie or series TMDB finds is used; persons are skipped.

The result

All values are strings unless it says otherwise. A value TMDB does not have is the string "None". The language is the one of the plugin's setting Language; the English text is used if TMDB has none in that language.

Key	Meaning
title, original_title	Title and original title of a movie
name, first_air_date	Title and first air date of a series
year	Year of release (or of the first air date)
tagline	The tagline
overview	The description
fulldescription	Tagline, genres, countries, year, description, cast, crew and seasons as one text, ready to show
genre	Genres, separated by comma
country	Country codes, separated by / (for example DE/US)
runtime	For a movie 123 min, for a series 3 Seasons / 30 Episodes (translated)
rating	Average vote with one decimal, for example 7.3
votes, votes_brackets	Number of votes, also as (1234)
cast	One line Name (Character) for each actor
crew	One line Name (Job) for each member of the crew
director	The directors, one per line. For a series Various (translated)
author	The screenplay writers, one per line. For a series its creators
studio	The production companies (a movie) or networks (a series), separated by comma
fsk	The German age rating without the +, for example 12, or an empty string
seasons	For a series one line for each season, for a movie an empty string
videos	For a movie a list of the YouTube videos TMDB knows: dictionaries with at least key (the YouTube id) and name
cover_url	The address of the cover (poster) picture, in the size set by Cover resolution
release_date, vote_average, vote_count, number_of_seasons, number_of_episodes	The raw values TMDB gave (numbers where TMDB gives numbers)

The dictionary has more entries than listed here (the raw data of TMDB). Rely on the ones above.

Providing the search of the details screen

In the details screen the key INFO calls a plugin of type WHERE_SEARCH with the title and the original title of the movie. Register one to make TMDBCockpit open, for example, a search in your media library:

def searchMovie(session, title, original_title, **kwargs):
    session.open(MyLibrarySearch, title or original_title)

def Plugins(**kwargs):
    return PluginDescriptor(name="My search", where=WHERE_SEARCH, fnc=searchMovie)

Without such a plugin, INFO shows No search provider registered.

Notes

• TMDBCockpit uses the API key in /etc/enigma2/tmdb_key.txt if there is one, otherwise its built-in key; see Your own API key.
• The pictures and the trailers are kept in /var/volatile/tmp/TMDBCockpit/ while the overview is open. The folder is removed when it is closed.
• A plugin that depends on TMDBCockpit lists enigma2-plugin-extensions-tmdbcockpit in its CONTROL/control, or checks for None as above, if the lookup is optional.