Container & Object Types (Modern API)

The modern API uses typed objects instead of generic XML containers.

ObjectContainer

The top-level container for returning content to the client.

Attribute	Type	Description
title1	str	Primary title (displayed in header).
title2	str	Secondary title.
art	str	Background art URL / resource path.
view_group	str	Name of a registered view group.
content	str	Content type hint (use ContainerContent constants).
no_history	bool	Don’t add to navigation history.
replace_parent	bool	Replace the parent container in navigation.
no_cache	bool	Disable caching of this container.
mixed_parents	bool	Contains items from multiple parent containers.
header	str	Header message text.
message	str	Message body text.
http_headers	dict	HTTP headers for requests.
identifier	str	Plugin identifier override.
source_title	str	Source title override.

Supported child types: DirectoryObject, NextPageObject, InputDirectoryObject, PopupDirectoryObject, PrefsObject, SearchDirectoryObject, PlaylistObject, MovieObject, VideoClipObject, EpisodeObject, SeasonObject, TVShowObject, ArtistObject / AlbumObject / PhotoObject / PhotoAlbumObject, TrackObject, MetadataItem, SearchResult, and all Video Extra Types.

add(obj)

Adds an object to the container.

extend(obj_list)

Adds all objects from a list or another container.

DirectoryObject

A navigable directory item.

Attribute	Type	Description
key	str or Callback	URL or callback to load contents.
title	str	Display title.
tagline	str	Subtitle / tagline.
summary	str	Description.
thumb	str	Thumbnail URL / resource path.
art	str	Background art URL / resource path.
duration	int	Duration (ms).

NextPageObject

Represents a “More…” pagination link. Same attributes as DirectoryObject. Only one instance can exist per container. If title is omitted, defaults to “More…”.

InputDirectoryObject

A directory that takes text input from the user.

Attribute	Type	Description
key	str or Callback	URL / callback, receives query parameter.
title	str	Display title.
prompt	str	Prompt text displayed to the user.
summary	str	Description.
thumb	str	Thumbnail.
art	str	Background art.

SearchDirectoryObject

A specialized search object that uses URL Services.

Attribute	Type	Description
identifier	str	Plugin identifier (defaults to current plugin).
name	str	Service name (defaults to first available).
title	str	Display title.
prompt	str	Prompt text.
summary	str	Description.
thumb	str	Thumbnail.
art	str	Background art.
term	str	Pre-filled search term.

PopupDirectoryObject

A directory displayed as a popup overlay. Same attributes as DirectoryObject (minus http_headers).

PrefsObject

Displays the plug-in’s preferences dialog.

Attribute	Type	Description
title	str	Display title.
summary	str	Description.
thumb	str	Thumbnail.

PlaylistObject

A playlist directory object.

Attribute	Type	Description
key	str or Callback	URL / callback for playlist contents.
title	str	Playlist title.
summary	str	Description.
thumb	str	Thumbnail.
radio	bool	Whether this is a radio-style playlist.

MovieObject

A browsable movie metadata item.

Attribute	Type	Description
url	str	URL for URL Service resolution.
key	str	Metadata URL.
rating_key	str	Unique rating key.
title	str	Movie title.
year	int	Year.
originally_available_at	datetime.date	Release date.
studio	str	Studio.
tagline	str	Tagline.
summary	str	Summary.
content_rating	str	Content rating.
duration	int	Duration (ms).
rating	float	Rating.
genres	list[str]	Genres.
directors	list[Person] or list[dict]	Directors.
writers	list[Person] or list[dict]	Writers.
roles	list[Person] or list[dict]	Cast.
thumb	str	Thumbnail URL.
source_icon	str	Source icon URL.
items	list[MediaObject]	Media objects (for direct play).

VideoClipObject

Same as MovieObject but with type = clip.

EpisodeObject

Same as MovieObject plus the following additional attributes:

Attribute	Type	Description
show	str	Show title.
season	int	Season number.
index	int	Episode number.
absolute_index	int	Absolute episode number.

SeasonObject

Non-media container for a season hierarchy.

TVShowObject

Non-media container for a show hierarchy.

TrackObject

A browsable audio track metadata item.

Attribute	Type	Description
url	str	URL for URL Service resolution.
title	str	Track title.
index	int	Track number.
artist	str	Artist name.
album	str	Album name.
duration	int	Duration (ms).
rating	float	Rating.
items	list[MediaObject]	Media objects.

ArtistObject / AlbumObject / PhotoObject / PhotoAlbumObject

Non-media containers corresponding to their model types.

MetadataItem

A container representing a node in a hierarchical metadata tree. Used in agent version 1+ object trees returned from PMS; not typically constructed directly in plugin code. MetadataItem children can be nested recursively.

Attribute	Type	Description
type	str	Media type identifier (e.g. "movie", "show", "season", "episode").
id	str	Unique identifier of the metadata item.
title	str	Display title.
guid	str	Plex GUID string (e.g. "com.plexapp.agents.imdb://tt1234567").
index	str	Positional index (season number, episode number, etc.).
originally_available_at	str	Original air / release date (ISO 8601 string).
score	str	Match confidence score (0–100).
thumb	str	Thumbnail URL.
matched	str	"1" if the item has been matched to a metadata source, "0" otherwise.

SearchResult

Represents a single candidate returned by an agent’s search() method when using the modern search API. This includes V0 agents with the tree parameter and V2 Agent.Artist.

Append SearchResult objects to the ObjectContainer passed as results via results.add(SearchResult(...)). SearchResult children can be nested to represent hierarchical results (e.g. episodes within a show).

Attribute	Type	Description
type	str	Media type identifier (e.g. 'artist', 'movie').
id	str	Source-specific identifier used to retrieve metadata in update(). For contributing agents, this is passed as the id parameter to the agent’s _update method. For primary agents, PMS uses this along with the plugin identifier to construct the GUID.
name	str	Display name of the result.
guid	str	Explicit Plex GUID string. If set, PMS uses this directly instead of constructing one from id.
index	str	Positional index.
year	int or str	Release year (converted to string in XML).
score	int	Match confidence score (0–100). Must be an integer — used for sorting results in descending order and for score-threshold checks during contributing agent matching. Contributing agents need a score above 75 to be considered a match.
thumb	str	Thumbnail URL.
matched	str	"1" if already matched.
parentName	str	Name of the parent item (e.g. artist name for an album result).
parentID	str	Identifier of the parent item.
parentGUID	str	Plex GUID of the parent item.
parentIndex	str	Index of the parent item (e.g. season number).

MediaObject

Represents a specific media version of a content item.

Attribute	Type	Description
parts	list[PartObject]	List of media parts.
bitrate	int	Overall bitrate (kbps).
aspect_ratio	str	Aspect ratio (e.g. "1.78").
audio_channels	int	Number of audio channels.
audio_codec	str	Audio codec (use AudioCodec constants).
video_codec	str	Video codec (use VideoCodec constants).
video_resolution	str	Resolution ("sd", "720", "1080", etc.).
container	str	Container format (use Container constants).
video_frame_rate	str	Frame rate.
duration	int	Duration (ms).
width	int	Video width (pixels).
height	int	Video height (pixels).
protocol	str	Protocol ("hls", "rtmp", "webkit", "embed", etc.).
optimized_for_streaming	bool	Whether the file is optimized for streaming.

PartObject

Represents a single file/stream of a media object.

Attribute	Type	Description
key	str or URL type	URL to the media stream.
file	str	Local file path.
duration	int	Duration (ms).
container	str	Container format.
streams	list[AudioStreamObject or VideoStreamObject]	Stream metadata.
http_headers	dict	HTTP headers for the request.
optimized_for_streaming	bool	Optimized for streaming flag.
protocol	str	Protocol type.

AudioStreamObject

Attribute	Type	Description
codec	str	Audio codec.
channels	int	Number of channels.
bitrate	int	Bitrate (kbps).
duration	int	Duration (ms).
language_code	str	ISO language code.
sampling_rate	int	Sampling rate (Hz).
index	str	Stream index (default: 1).
selected	bool	Whether this stream is selected.

VideoStreamObject

Attribute	Type	Description
codec	str	Video codec.
bitrate	int	Bitrate (kbps).
width	int	Width (pixels).
height	int	Height (pixels).
duration	int	Duration (ms).
frame_rate	str	Frame rate.
level	str	Codec level.
profile	str	Codec profile.
index	str	Stream index (default: 0).
selected	bool	Whether this stream is selected.

WebVideoURL

WebVideoURL(url) → str

Wraps a URL for WebKit playback.

HTTPLiveStreamURL

HTTPLiveStreamURL(url) → str

Wraps a URL for HLS playback.

RTMPVideoURL

RTMPVideoURL(url, clip=None, live=False, swf_url=None, app=None, args=None, **kwargs) → str

Constructs an RTMP URL with parameters.

WindowsMediaVideoURL

WindowsMediaVideoURL(url, width=None, height=None) → str

Wraps a URL for Silverlight / WMV playback.

EmbedURL

EmbedURL(url) → str

Wraps a URL for embedded player playback.

IndirectResponse

IndirectResponse(cls, key, url=None, metadata_key=None, rating_key=None, metadata_kwargs={}, **kwargs)

Creates an indirect response container for deferred content resolution.