Skip to content

How it works

Jump to bottom
Markus edited this page Apr 20, 2022 · 10 revisions

This page describes how the plugin finds the best match for an event.

Create a list of possible matches

Goal is, that the correct match is in this list. The search APIs of the supported databases are used. Unfortunately, these APIs lack some capabilities.

Example 1:

  • In the EPG, the movie is displayed as "Jackie Chan: Projekt B".
  • There is nor search result for "Jackie Chan: Projekt B"
  • The plugin will split the text at ":", and search for "Projekt B"
  • This works, and the correct movie 21521 is in the result list

Example 2:

  • In the EPG, the movie is displayed as "Das Kabinett des Dr. Parnassus"
  • There is nor search result for "Das Kabinett des Dr. Parnassus"
  • Here, we are lost: The plugin does not know where to split this text
  • An entry in override.conf is required: "substitute;Das Kabinett des Dr. Parnassus;Das Kabinett des Doktor Parnassus"
  • Note: Real good search engines know that "Dr." is the same as "Doktor", and find such matches. For this plugin, that feature is out of scope, you have to use override.conf or rename the recording

Example 3:

  • In the EPG, the event is displayed as "Tatort: Kartenhaus"
  • The plugin will search for "Tatort", to find the correct TV Show
  • The text "Kartenhaus" will be used to find the correct season/episode

Identify the correct match

For each entry in the list of possible matches a probability between 0 and 1 is calculated. This is done in several steps.

Step 1: Use information returned by the search API

Which information is returned depends on the database. The plugin uses everything available, like:

  • Text (Name, alias names, original name)
  • Year
  • Vote average and vote count

The plugin compares the probability of the best match with the probability of the second best match. If the distance is high enough, the best match is found. Otherwise, step 2 is applied:

Step 2: Use additional information, which is cached in the plugin's database

For all possible matches with a probability near to the probability of the best match additional information is used to re-calculate the probability. Such additional information is cached in the plugin's database, and includes:

  • Duration
  • Actors
  • Director, writer
  • Text (add Tagline)
  • Vote average and vote count

Again, the plugin compares the probability of the best match with the probability of the second best match. If required (the distance is not high enough), step 3 is applied:

Step 3: Use additional information, which must be retrieved from the internet databases

Currently, this applies only to the episode list. This is not cached in the plugin's database, as it is rather large and not required in most cases. So, for TV shows, an episode match is an additional information.

Combining all information to one final value

Each single information is error prone, for example the information in the internet database can be wrong, the EPG information can be wrong, ...

Even in such a situation, in most cases, the algorithm still finds the correct match. The wrong information is "overruled" by correct information.

To achieve this, a probability / matching value for each peace of information is calculated and multiplied with a weight factor. All these weighted probability / matching values are summed up, and divided by a norming factor. The result is the overall matching probability of this possible match. Example:

  • searchResultTvMovie::log, id: -72073, title: "star trek - deep space nine"
  • searchResultTvMovie::log, i: 0, match: 0.875000, weight 0,600000, desc: Text
  • searchResultTvMovie::log, i: 1, match: 1.000000, weight 0,100000, desc: Year
  • searchResultTvMovie::log, i: 2, match: 0.890064, weight 0,200000, desc: Vote, ..
  • searchResultTvMovie::log, i: 3, match: 1.000000, weight 0,200000, desc: Duration
  • searchResultTvMovie::log, i: 4, match: 0.353553, weight 0,300000, desc: Actors
  • searchResultTvMovie::log, i: 5, match: 0.000000, weight 0,100000, desc: Director Writer
  • searchResultTvMovie::log, getMatch(): 0.739338 . This is the final probability

Overall, this works very well in most cases. For some events, there is really no (or almost no) information available. Example: "heute". Title is "heute", subtitle is not available, and there is no description. We only have this text and the duration. So, some help is required in override.conf: "settype;heute;series".

Another example: "Wetter", without title and subtitle. There is no correct match in the internet databases, still the plugin will find a wrong match. Solution again with override.conf: "ignore;Wetter"

Clone this wiki locally