Custom TMDB example agent does not pass TV series ratings to Plex

Dev Community Dev/API Corner
,
1

When using the custom TMDB metadata agent found at GitHub - plexinc/tmdb-example-provider for a TV library, series ratings are not being passed to Plex correctly. They do seem to be stored in a ratings array, but they don’t show up in the Plex UI, and the XML does not include them. It also bears mentioning that the audienceRatingImage is not present, and the year of release is different.***

For comparison, here is a TMDB metadata agent XML response for a series, and then a Plex Series agent response for the same series:

TMDB example:

{
“ratingKey”: “118134”,
“key”: “/library/metadata/118134/children”,
“guid”: “tv.plex.agents.custom.example.themoviedb.tv://show/tmdb-show-1972”,
“slug”: “battlestar-galactica-2003”,
“studio”: “David Eick Productions”,
“type”: “show”,
“title”: “Battlestar Galactica (2003)”,
“contentRating”: “TV-14”,
“contentRatingAge”: 15,
“summary”: “When an old enemy, the Cylons, resurface and obliterate the 12 colonies, the crew of the aged Galactica protect a small civilian fleet - the last of humanity - as they journey toward the fabled 13th colony, Earth.”,
“index”: 1,
“year”: 2004,
“tagline”: “The fight to save humanity rages on.”,
“thumb”: “/library/metadata/118134/thumb/1770283508”,
“art”: “/library/metadata/118134/art/1770283508”,
“theme”: “/library/metadata/118134/theme/1770283508”,
“duration”: 2640000,
“originallyAvailableAt”: “2004-10-18”,
“leafCount”: 13,
“viewedLeafCount”: 1,
“childCount”: 1,
“addedAt”: 1578143760,
“updatedAt”: 1770283508,

… arrays…
}

Plex Series agent:

{

“ratingKey”: “118134”,
“key”: “/library/metadata/118134/children”,
“guid”: “plex://show/5d9c0871ba6eb9001fba43ff”,
“slug”: “battlestar-galactica-2003”,
“studio”: “David Eick Productions”,
“type”: “show”,
“title”: “Battlestar Galactica (2003)”,
“contentRating”: “TV-14”,
“contentRatingAge”: 15,
“summary”: “When an old enemy, the Cylons, resurface and obliterate the 12 colonies, the crew of the aged Galactica protect a small civilian fleet - the last of humanity - as they journey toward the fabled 13th colony, Earth.”,
“index”: 1,
“audienceRating”: 8.2,
“year”: 2004,
“tagline”: “The fight to save humanity rages on.”,
“thumb”: “/library/metadata/118134/thumb/1770281738”,
“art”: “/library/metadata/118134/art/1770281738”,
“theme”: “/library/metadata/118134/theme/1770281738”,
“duration”: 2640000,
“originallyAvailableAt”: “2004-10-18”,
“leafCount”: 13,
“viewedLeafCount”: 1,
“childCount”: 1,
“addedAt”: 1578143760,
“updatedAt”: 1770281738,
“audienceRatingImage”: “themoviedb://image.rating”,

… arrays …

}

PMS version: 1.43.0.10467

As a developer note, it would be great if there was a custom metadata agents page in the plex support docs that contained a link to the (maintained) TMDB example, as well as an example of expected output for a movie, series, etc. The API docs and TMDB example could be deeper resources, but a quick authoritative reference in the support docs would be great IMHO and likely encourage development. It would also be interesting to know where Plex Series scanner gets the data for certain fields, what the fallback system is for missing data etc. so we can replicate that logic more closely if we want to with our agents (e.g. the above example shows data from TMDB, some not, most glaringly the “year” value differs and I don’t know what source is providing it).

2

Minor edit: I originally pasted the response from a custom TVDB provider by mistake, i have pasted the proper TMDB example response now. FTR these are the XML responses from plex, after the metadata has been added by the agent.

Follow-up:

Adding Plex Series as a secondary agent in the provider (with TMDB example as the primary) should fix this issue if I understand the logic correctly (if a field is missing in agent A, go to agent B, etc) but that doesn’t seem to be working for me either.

3

The example TMDB agent isn’t a complete implementation, it’s just an example to help folks get started.

There is info in the developer docs outlining the ratings: https://developer.plex.tv/pms/#section/API-Info/Metadata-Response (see under Rating Array).

4

I have built my own provider and I’m returning both Rating array and audienceRating and rating properties, but the ratings do not populate on items.

The documentation you linked does not include documentation on the rating and audienceRating properties, which is odd.

I am sure I’m just doing something wrong, but at this point, I’m at a loss. But the Rating array doesn’t seem like its enough, and my other library from the default provider has rating/audienceRating set on the root of the item.

5

Can you post what the Rating array looks like?

6

To be clear, the difference between an item scraped with my provider, and the official provider, is that when i look at the XML metadata for an item scraped with the official provider, I see rating and audienceRating at the top level, and the rating show in the web UI and in the plex app on the shield.

My metadata provider returns rating and audienceRating but plex doesn’t set the top level rating and audienceRating in the item on plex when it refreshes, it does not show up in the XML either. The icons do not show up visually, the ratings do not show up on the item either.

I’ve tried with all kinds of combinations, including disabling trakt in here, no effect.

Here is the Rating Array my provider returns:

        "Rating": [
          {
            "image": "imdb://image.rating",
            "type": "audience",
            "value": 7.5
          },
          {
            "image": "themoviedb://image.rating",
            "type": "audience",
            "value": 5.4
          },
          {
            "image": "trakt://image.rating",
            "type": "audience",
            "value": 7.53
          }
        ],

This is the full payload:

{
  "MediaContainer": {
    "identifier": "tv.plex.agents.custom.posterity.tv",
    "Metadata": [
      {
        "audienceRating": 7.53,
        "audienceRatingImage": "trakt://image.rating",
        "duration": 1260000,
        "Guid": [
          {
            "id": "tmdb://6388496"
          },
          {
            "id": "tvdb://11248102"
          },
          {
            "id": "imdb://tt35505522"
          },
          {
            "id": "trakt://13331391"
          }
        ],
        "guid": "tv.plex.agents.custom.posterity.tv://episode/4d89feaf_ec89_4ab9_9891_9aba5519610b",
        "Image": [
          {
            "alt": "Team Building",
            "type": "background",
            "url": "/api/plex/artwork/4d89feaf-ec89-4ab9-9891-9aba5519610b/background"
          },
          {
            "alt": "Team Building",
            "type": "background",
            "url": "/api/plex/artwork/4d89feaf-ec89-4ab9-9891-9aba5519610b/background"
          },
          {
            "alt": "Team Building",
            "type": "snapshot",
            "url": "/api/plex/artwork/4d89feaf-ec89-4ab9-9891-9aba5519610b/poster"
          }
        ],
        "key": "/library/metadata/4d89feaf_ec89_4ab9_9891_9aba5519610b",
        "originallyAvailableAt": "2025-01-01",
        "rating": 7.5,
        "ratingImage": "imdb://image.rating",
        "Rating": [
          {
            "image": "imdb://image.rating",
            "type": "audience",
            "value": 7.5
          },
          {
            "image": "themoviedb://image.rating",
            "type": "audience",
            "value": 5.4
          },
          {
            "image": "trakt://image.rating",
            "type": "audience",
            "value": 7.53
          }
        ],
        "ratingKey": "4d89feaf_ec89_4ab9_9891_9aba5519610b",
        "summary": "The teachers prepare for the upcoming school year with new faces and big changes on the horizon. Ava makes a big announcement that shocks Jacob and Melissa.",
        "title": "Team Building",
        "type": "episode",
        "year": 2025,
        "thumb": "/api/plex/artwork/4d89feaf-ec89-4ab9-9891-9aba5519610b/poster",
        "art": "/api/plex/artwork/4d89feaf-ec89-4ab9-9891-9aba5519610b/background",
        "parentRatingKey": "bcdd2b2d_e34f_4f54_8d9d_3f2aec1bcda2",
        "parentKey": "/library/metadata/bcdd2b2d_e34f_4f54_8d9d_3f2aec1bcda2",
        "parentGuid": "tv.plex.agents.custom.posterity.tv://season/bcdd2b2d_e34f_4f54_8d9d_3f2aec1bcda2",
        "parentType": "season",
        "parentTitle": "Season 5",
        "index": 1,
        "grandparentRatingKey": "d4b3eecb_aacc_4d1d_bffc_8fa01cf27b94",
        "grandparentKey": "/library/metadata/d4b3eecb_aacc_4d1d_bffc_8fa01cf27b94",
        "grandparentGuid": "tv.plex.agents.custom.posterity.tv://show/d4b3eecb_aacc_4d1d_bffc_8fa01cf27b94",
        "grandparentType": "show",
        "grandparentTitle": "Abbott Elementary",
        "parentIndex": 5
      }
    ],
    "offset": 0,
    "size": 1,
    "totalSize": 1
  }
}