Skip to content

Metadata Remap

Jump to bottom
iamkroot edited this page Nov 26, 2022 · 3 revisions
  • By default, we rely on the file path for extracting media details like title, episode, etc.
    • Caveat: For Plex, we use its library metadata instead of using the path.
  • But the path might not always contain all the required info. Or in the case of streaming videos, the URL might be garbled.
  • The scrobbler provides multiple ways to modify the media info extraction logic.

remap_rules.toml

Simple ID change

  • In the simplest case, the app might have mis-identified a show/movie based on the title.
  • You may find that the app is scrobbling the wrong show/movie, or that it gave a 404 Not Found, or Trakt search yielded no results in the log file.
  • The fix is to manually specify the desired show/movie ID.
  • To do so, you need to open remap_rules.toml in a file editor and specify the Trakt ID of the media you want (see File format to know where to place this.)
  • How to find the Trakt ID? Simply open the media page on trakt.tv and get the last part of the webpage url.

Example

  • Suppose you want to scrobble the new Mulan live-action movie instead of the older animated version.
  • By default, if there is no year present in the file path (like: D:\Movies\Mulan.mkv), Trakt search will return the animated version first, and we will pick that. The app has no way of distinguishing between the two versions.
  • You can specify the following to override the movie (see File format to know where to place this)-
[[rules]]
# specify which media you want to override
match.title = "Mulan"

# now, specify the override
type = "movie"
id.trakt_slug = "mulan-2020" # (got the slug from url)
  • Alternatively, we could have also used the full path to match instead of the title.
    • note that the separator should have forward slashes (/ instead of \), even on Windows.
match.path = "D:/Movies/Mulan.mkv"

Advanced remapping

  • We also support cases when you need to change the episode/season numbers, or any other arbitrary information. See schema

File format

schema

there should be a toplevel key "rules", which is a list of the following-
[match]
  - one or more of path, title, season, episode, year
  - path should be valid a Python regex pattern
    - you can also capture substrings using "(?P<name>pattern)" syntax. These will override the default-extracted values from guessit.
  - season, episode, year support ranges.
      - For instance, 'season: "1:3,5"' will match any season in {1,2,3,5}
  - if needed, we can add a "fuzzy-title" in the future to do edit-distance based matching
  - specifying multiple fields means all of them should match.
[type]
  - one of "episode" or "movie"
[id]
  - one of trakt_slug, trakt_id, or title (to select top result)
  - can use placeholders for extracted values like "{episode}", "{title}", "{year}", etc.
     - the placeholder names should match the extracted guessit keys or regex capture group names
  - "title" can contain an optional year inside parentheses. Eg: "The Man from Earth (2007)"
[season]
  - optional. If not provided, the extracted value from path/regex will be used.
  - any number starting from 0
  - 0 corresponds to "Specials" season on Trakt
[episode_delta]
  - optional. Default is 0
  - any integer (positive or negative)
  - will be added to the episode number extracted from path/regex

Sample usecases

  1. Incorrect ID (explained above)
[[rules]]
# specify which media you want to override
match.title = "Mulan"

# now, specify the override
type = "movie"
id.trakt_slug = "mulan-2020" # (got the slug from url)
  1. Playing some file from youtube-
[[rules]]
match.path = "https://www\\.youtube\\.com/watch\\?v=eJ3RzGoQC4s"
id.trakt_slug = "the-century-of-the-self"
type = "episode"

season = 1
episode = "1:4"
  • The video at the URL in match.path contains all 4 episodes for the documentary "The Century of the Self".
    • We can capture this by specifying episode = "1:4"
  • Note that match.path is a regex pattern, so it needs to escape regex meta characters
  • This will not work unless we also have https://www.youtube.com/watch?v=eJ3RzGoQC4s added to fileinfo.whitelist section in the config.
    • trakts config set --add fileinfo.whitelist "https://www.youtube.com/watch?v=eJ3RzGoQC4s"
    • Note that the path whitelist entry in not a regex- no need to escape any character.
  1. Some complex matching
  • See #214 for a large example.

Custom Regexes

Clone this wiki locally