Metadata Model Types

Metadata models define the structure of metadata that agents populate. Each model type has typed attributes defined using Template.* types.

Movie

Attribute	Type	Description
title	str	Movie title.
year	int	Release year.
originally_available_at	datetime.date	Release date.
studio	str	Production studio.
tagline	str	Tagline.
summary	str	Plot summary.
trivia	str	Trivia text.
quotes	str	Notable quotes.
content_rating	str	Content rating (e.g. PG-13).
content_rating_age	int	Content rating minimum age.
duration	int	Duration in milliseconds.
rating	float	Critic rating.
audience_rating	float	Audience rating.
rating_image	str	Rating image identifier. Tells Plex clients which icon to display next to the critic `rating`.
audience_rating_image	str	Rating image identifier. Tells Plex clients which icon to display next to the `audience_rating`.
original_title	str	Original title (foreign language).
title_sort	str	Sort title.
genres	Set[str]	Genre tags.
tags	Set[str]	Tag strings. Serialized as `<Tag>` elements.
collections	Set[str]	Collection names.
similar	Set[str]	Similar item names.
writers	Set[Person]	Writers.
directors	Set[Person]	Directors.
producers	Set[Person]	Producers.
roles	Set[Person]	Cast members (actors).
countries	Set[str]	Country names.
reviews	Set[Review]	Reviews.
chapters	Set[Chapter]	Chapter markers.
posters	ProxyContainer	Poster images.
art	ProxyContainer	Background art images.
banners	ProxyContainer	Banner images.
themes	ProxyContainer	Theme music files.
extras	extras container	Video extras (Trailer, BehindTheScenes, etc.).

TV_Show

Attribute	Type	Description
title	str	Show title.
summary	str	Show summary.
originally_available_at	datetime.date	First air date.
content_rating	str	Content rating.
studio	str	Network / studio.
duration	int	Default episode duration (ms).
rating	float	Rating.
genres	Set[str]	Genres.
tags	Set[str]	Tag strings. Serialized as `<Tag>` elements.
collections	Set[str]	Collections.
similar	Set[str]	Similar item names.
roles	Set[Person]	Cast members.
countries	Set[str]	Countries.
posters	ProxyContainer	Poster images.
banners	ProxyContainer	Banner images.
art	ProxyContainer	Background art.
themes	ProxyContainer	Theme music.
seasons	Map[Season]	Seasons keyed by season number.
extras	extras container	Video extras.

Season

Attribute	Type	Description
summary	str	Season summary.
posters	ProxyContainer	Season posters.
banners	ProxyContainer	Season banners.
art	ProxyContainer	Season art.
episodes	Map[Episode]	Episodes keyed by episode number.
extras	extras container	Video extras.

Episode

Attribute	Type	Description
title	str	Episode title.
summary	str	Episode summary.
originally_available_at	datetime.date	Air date.
rating	float	Rating.
duration	int	Duration (ms).
content_rating	str	Content rating.
content_rating_age	int	Content rating minimum age.
absolute_index	int	Absolute episode index (for absolute numbering).
writers	Set[Person]	Writers.
directors	Set[Person]	Directors.
producers	Set[Person]	Producers.
guest_stars	Set[Person]	Guest stars.
tags	Set[str]	Tag strings. Serialized as `<Tag>` elements.
thumbs	ProxyContainer	Episode thumbnails.
extras	extras container	Video extras.

Artist

Attribute	Type	Description
title	str	Artist name.
title_sort	str	Sort name.
summary	str	Biography.
genres	Set[str]	Genres.
moods	Set[str]	Moods.
styles	Set[str]	Styles.
similar	Set[str]	Similar item names.
concerts	Set[Concert]	Concert info.
countries	Set[str]	Countries.
posters	ProxyContainer	Artist images.
art	ProxyContainer	Background art.
themes	ProxyContainer	Theme music.
extras	extras container	Music videos, interviews, etc.

Album

Attribute	Type	Description
title	str	Album title.
title_sort	str	Sort title.
summary	str	Album summary / review.
studio	str	Record label.
originally_available_at	datetime.date	Release date.
available_at	datetime.date	Availability date.
genres	Set[str]	Genres.
styles	Set[str]	Styles.
moods	Set[str]	Moods.
album_format	Set[str]	Album format.
album_type	Set[str]	Album type.
producers	Set[Person]	Producers.
countries	Set[str]	Countries.
posters	ProxyContainer	Album cover images.
art	ProxyContainer	Background art.
tracks	Map[Track]	Tracks keyed by track index.

Track

Attribute	Type	Description
title	str	Track title.
title_sort	str	Sort title.
original_title	str	Original title.
rating	float	Rating.
rating_count	int	Number of ratings.
index	int	Track number.
disc_index	int	Disc number.
track_index	int	Track index.
tempo	int	BPM / tempo.
moods	Set[str]	Moods.
tags	Set[str]	Tag strings. Serialized as `<Tag>` elements.
extras	extras container	Music video extras.
lyrics	ProxyContainer	Lyrics (supports Media, Remote, LocalFile proxies).

Photo

Attribute	Type	Description
title	str	Photo title.
year	int	Year taken.
originally_available_at	datetime.date	Date taken.
studio	str	Studio / camera.
tagline	str	Tagline.
summary	str	Description.
content_rating	str	Content rating.
writers	Set[Person]	Photographers.
directors	Set[Person]	Directors.
producers	Set[Person]	Producers.
roles	Set[Person]	People in the photo.
countries	Set[str]	Countries.

PhotoAlbum

Same attributes as Photo.

Person

Attribute	Type	Description
name	str	Person’s name.
role	str	Role name (for cast).
photo	str	URL to a photo.

Review

Attribute	Type	Description
author	str	Reviewer name.
source	str	Review source.
image	str	Image URL.
link	str	Review URL.
text	str	Review text.

Chapter

Attribute	Type	Description
title	str	Chapter title.
start_time_offset	int	Start time in milliseconds.
end_time_offset	int	End time in milliseconds.

Concert

Attribute	Type	Description
title	str	Concert title.
venue	str	Venue name.
city	str	City.
country	str	Country.
date	str	Date string.
url	str	URL for more info.

Video Extra Types

The extras attribute on metadata models is an ObjectContainer-based container that accepts extra video objects. Each extra type is a class published as a global name in the sandbox (e.g. TrailerObject). All extras inherit from VideoExtra (a MetadataModel subclass).

Note

The extras container is not a Set or Map. It is an ObjectContainerObject that wraps an ObjectContainer. Use metadata.extras.add(...) to add items.

Warning

Extras cannot be deserialized. The framework’s ObjectContainerObject._deserialize() is a no-op. This means that each time update() is called, the extras container starts empty — the agent must re-populate all extras on every update. Extras saved by one agent cannot be read back by the same or another agent in a subsequent call.

Extras per Media Type

Not all metadata models support extras. The allowed extra types differ by model:

Model	Allowed Extra Types
Movie	TrailerObject, DeletedSceneObject, BehindTheScenesObject, InterviewObject, SceneOrSampleObject, FeaturetteObject, ShortObject, OtherObject
TV_Show	(same as Movie)
Season	(same as Movie)
Episode	(same as Movie)
Artist	MusicVideoObject, LiveMusicVideoObject, LyricMusicVideoObject, InterviewObject, BehindTheScenesObject, ConcertVideoObject
Track	MusicVideoObject, LyricMusicVideoObject
Album	No extras — Album does not have an `extras` attribute.
Photo / PhotoAlbum	No extras — Photo and PhotoAlbum do not have an `extras` attribute.

Adding extras:

# Online extras — use 'url' to specify a URL (resolved via URL Services)
trailer = TrailerObject(
    url='https://example.com/trailer.mp4',
    title='Official Trailer',
    year=2020,
    thumb='https://example.com/thumb.jpg'
)
metadata.extras.add(trailer)

# Local file extras — use 'file' to specify a local file path
# (Agent plug-ins only; LocalMedia.bundle uses this pattern)
metadata.extras.add(BehindTheScenesObject(
    title='Making Of',
    file='/path/to/behindthescenes.mp4'
))

# Music video extras on an Artist
metadata.extras.add(MusicVideoObject(
    url='https://example.com/musicvideo.mp4',
    title='Song Title',
    album='Album Name'
))

Available extra types

Type	relation_type	Description
TrailerObject	trailer	Movie / show trailer.
DeletedSceneObject	deletedScene	Deleted scene.
BehindTheScenesObject	behindTheScenes	Behind-the-scenes footage.
InterviewObject	interview	Interview clip.
SceneOrSampleObject	sceneOrSample	Scene or sample clip.
FeaturetteObject	featurette	Featurette.
ShortObject	short	Short film.
OtherObject	other	Other extra.
MusicVideoObject	musicVideo	Music video.
LiveMusicVideoObject	liveMusicVideo	Live music video.
LyricMusicVideoObject	lyricMusicVideo	Lyric music video.
ConcertVideoObject	concert	Concert video.

Common extra attributes

All extra types accept these attributes in their constructor and as settable properties. The first group comes from the MetadataObject superclass (added by objectkit.py when publishing the class); the second group comes from the VideoExtra model definition.

Source attributes (MetadataObject):

Attribute	Type	Description
url	str	Video URL. PMS resolves this via URL Services to obtain playable media. Optional — use either `url` or `file`.
file	str	Local file path to the video. Agent plug-ins only — this attribute is not available in channel (Resource) plug-ins. Optional — use either `url` or `file`.
http_headers	dict	HTTP headers to send when fetching the URL.
user_agent	str	User-Agent header (shorthand).
http_cookies	str	Cookie header (shorthand).
deferred	bool	Whether this extra should be lazily resolved.
source_icon	str	Icon for the source provider.

Model attributes (VideoExtra):

Attribute	Type	Description
title	str	Title.
year	int	Year.
originally_available_at	datetime.date	Release date.
studio	str	Studio.
tagline	str	Tagline.
summary	str	Summary.
writers	Set[Person]	Writers.
directors	Set[Person]	Directors.
producers	Set[Person]	Producers.
roles	Set[Person]	Cast.
countries	Set[str]	Countries.
index	int	Sort index.
thumb	str	Thumbnail URL (synthetic — written to XML but not persisted to model).
art_url	str	Art URL (synthetic, serialized as `art` in XML).

Music-video extra attributes

MusicVideoObject, LiveMusicVideoObject, LyricMusicVideoObject, and ConcertVideoObject also support:

Attribute	Type	Description
album	str	Associated album name (serialized as `parentTitle` in XML).

Rating Image Identifiers

The rating_image and audience_rating_image attributes on metadata models are not URLs pointing to image files. They are identifier strings in a URI scheme format that Plex clients (and the server) map to built-in icons for displaying rating badges next to scores (e.g. the Rotten Tomatoes “Fresh” tomato or the IMDb logo).

Format

Rating image identifiers follow the pattern:

<source>://image.rating[.<variant>]

Where <source> is a recognized rating provider and <variant> specifies the icon variant.

Known Identifiers

The following identifiers are used by the official PlexMovie agent:

Identifier	Description
`imdb://image.rating`	IMDb rating icon. Used for `rating_image` when IMDb is the rating source.
`rottentomatoes://image.rating.certified`	Rotten Tomatoes “Certified Fresh” badge.
`rottentomatoes://image.rating.ripe`	Rotten Tomatoes “Fresh” tomato.
`rottentomatoes://image.rating.rotten`	Rotten Tomatoes “Rotten” splat.
`rottentomatoes://image.rating.upright`	Rotten Tomatoes audience “Upright” popcorn (for `audience_rating_image`).
`rottentomatoes://image.rating.spilled`	Rotten Tomatoes audience “Spilled” popcorn (for `audience_rating_image`).

Usage

Set rating_image and audience_rating_image alongside their corresponding numeric scores:

def update(self, metadata, media, lang, force=False):
    # IMDb rating
    metadata.rating = 7.5
    metadata.rating_image = 'imdb://image.rating'
    metadata.audience_rating = 0.0
    metadata.audience_rating_image = None

    # Rotten Tomatoes ratings
    metadata.rating = 8.5                                     # critics score / 10
    metadata.rating_image = 'rottentomatoes://image.rating.certified'
    metadata.audience_rating = 9.2                             # audience score / 10
    metadata.audience_rating_image = 'rottentomatoes://image.rating.upright'

Note

The rating, rating_image, audience_rating, and audience_rating_image attributes are linked in the framework’s metadata combination pipeline. When rating is selected from a particular agent during combination, all four linked attributes are taken from the same agent. This means you should always set both the numeric rating and the corresponding image identifier together.

To clear a rating image, set it to an empty string ('') or None.

Can Plugins Define Custom Image Identifiers?

No. The mapping from identifier strings to actual images is handled by the Plex Media Server and Plex clients internally. Only the identifiers recognized by PMS (such as those listed above) will render icons. Setting a custom identifier like myplugin://image.rating.good will not cause an error, but Plex clients will not display any icon for it.

If you need to display a rating from a different source, you can:

Use one of the existing identifiers that closest represents your rating style.
Set only the numeric rating / audience_rating without an image identifier (the Plex UI will display the score without a provider icon).