Plex Plugin Docs
Getting Started
Overview
Bundle Structure
How the API is Exposed
Architecture
Framework Bootstrap
API Kit System
Modelling System
Framework Versions
Inter-Plugin Communication
Source Code Layout
Sandbox & Code Execution
How It Works
File Types
Naming Restrictions
Available Builtins
Builtins from RestrictedPython
safe_builtins
Additional builtins added by the sandbox
Blocked Builtins
Statement Restrictions
AST Rewrites
Import System
Policy System
Elevated Policy Details
Summary Table
Plugin Lifecycle & Entry Points
Start
ValidatePrefs
Info.plist Structure
Minimal Example
Info.plist Keys Reference
PlexPluginClass Values
PlexMediaTypes
Service Keys
Full Agent Example
Full Service Bundle Example
Preferences
Preference Types
Accessing Preferences
Metadata Agent Plugins
Legacy Metadata Agent (V0)
Agent Base Classes
Agent.Movies
Agent.TV_Shows
Agent.Artist
Agent.Album
Agent.Photos
Agent Class Attributes
search(self, results, media, lang, manual=False, tree=None)
Using the
tree
Parameter
update(self, metadata, media, lang, force=False)
Example Agent
Media Types
Media.Movie
Media.TV_Show
Media.Artist
Media.Album
MediaTree
all_parts() → list[MediaPart]
MediaItem
MediaPart
MediaStream
MetadataSearchResult
Modern Metadata Agent (V2)
Agent Setup
search(self, results, tree, hints, lang)
update(self, metadata, media, lang)
Example Agent
Metadata Model Types
Movie
TV_Show
Season
Episode
Artist
Album
Track
Photo
PhotoAlbum
Person
Review
Chapter
Concert
Video Extra Types
Extras per Media Type
Available extra types
Common extra attributes
Music-video extra attributes
Rating Image Identifiers
Format
Known Identifiers
Usage
Can Plugins Define Custom Image Identifiers?
Channel Plugins
Channel Plugins
How It Works
Info.plist for Channel Plugins
Bundle Structure
Entry Point
Defining Sub-Pages
Linking Pages with Callback
Playable Media Items
Indirect Playback
Start Function
User Preferences
Pagination
Search
Complete Example
Service API
Directory Structure
Old-style (plist-declared)
New-style (ServiceInfo.plist)
Shared Code
URL Services
NormalizeURL(url) → str
MetadataObjectForURL(url) → MetadataObject
MediaObjectsForURL(url) → list
URL Service API (consumer side)
Testing a URL service
Using URL services from plug-in code
Search Services
Search(query) → ObjectContainer
Search Service API (consumer side)
Testing a search service
Related Content Services
RelatedContentForMetadata(metadata) → ObjectContainer
Testing a related content service
SharedCodeService
Common API
Global Functions & Decorators
@handler
@route
Callback
@indirect
@deferred
@expose
@thread (decorator)
@spawn
@lock (decorator)
@parallelize / @parallel / @task
Template Attribute Types
Value Types
Set
add(value)
clear()
new() → Record instance
find(**kwargs) → Record or None
Map
keys() → list
validate_keys(valid_keys)
ProxyContainer
validate_keys(valid_keys)
Link
Container & Object Types (Modern API)
ObjectContainer
add(obj)
extend(obj_list)
DirectoryObject
NextPageObject
InputDirectoryObject
SearchDirectoryObject
PopupDirectoryObject
PrefsObject
PlaylistObject
MovieObject
VideoClipObject
EpisodeObject
SeasonObject
TVShowObject
TrackObject
ArtistObject / AlbumObject / PhotoObject / PhotoAlbumObject
MetadataItem
SearchResult
MediaObject
PartObject
AudioStreamObject
VideoStreamObject
WebVideoURL
HTTPLiveStreamURL
RTMPVideoURL
WindowsMediaVideoURL
EmbedURL
IndirectResponse
Container & Object Types (Legacy API)
MediaContainer
Append(obj)
Count(x) → int
Index(x) → int
Extend(x)
Insert(i, x)
Pop(i) → item
Remove(x)
Reverse()
Sort(attr, descending=False)
Clear()
DirectoryItem
PopupDirectoryItem
InputDirectoryItem
VideoItem
WebVideoItem
RTMPVideoItem
PhotoItem
TrackItem
PrefsItem
Function
IndirectFunction
MessageContainer
Redirect
DataObject
Proxy Objects
Proxy.Media
Proxy.Preview
Proxy.LocalFile
Proxy.Remote
Usage Examples
Networking API
HTTP
Request(url, values=None, headers={}, cacheTime=None, encoding=None, errors=None, timeout=GLOBAL_DEFAULT_TIMEOUT, immediate=False, sleep=0, data=None, follow_redirects=True, method=None) → HTTPRequest
CacheTime → float
Headers → dict
CookiesForURL(url) → str
SetPassword(url, username, password, realm=None)
PreCache(url, values=None, headers={}, cacheTime=None, encoding=None, errors=None)
Cookies → CookieJar
ClearCookies()
ClearCache()
HTTPRequest
Network
Address → str
PublicAddress → str
Hostname → str
Timeout → float
Socket() → socket
XMLRPC
Proxy(url, encoding=None) → ServerProxy
Parsing API
JSON
ObjectFromString(string, encoding=None) → dict or list
ObjectFromURL(url, …) → dict or list
StringFromObject(obj) → str
XML
Element(name, text=None, **kwargs) → _Element
StringFromElement(el, encoding=’utf8’) → str
ElementFromString(string, encoding=None) → _Element
ElementFromURL(url, …) → _Element
ObjectFromString(string) → ObjectifiedElement
ObjectFromURL(url, …) → ObjectifiedElement
StringFromObject(obj, encoding=’utf-8’) → str
HTML
Element(name, text=None, **kwargs) → HtmlElement
StringFromElement(el, encoding=’utf8’) → str
ElementFromString(string) → HtmlElement
ElementFromURL(url, …) → HtmlElement
Plist
ObjectFromString(string) → dict or list
ObjectFromURL(url, …) → dict or list
StringFromObject(obj) → str
RSS
FeedFromString(string) → feedparser dict
FeedFromURL(url, …) → feedparser dict
YAML
ObjectFromString(string) → object
ObjectFromURL(url, …) → object
Data & Persistence API
Data
Load(item) → str
Save(item, data)
LoadObject(item) → object
SaveObject(item, obj)
Exists(item) → bool
Remove(item)
Dict
Save()
Reset()
Utility API
String
Encode(s) → str
Decode(s) → str
Base64Encode(s, with_newlines=False) → str
Base64Decode(s) → str
Quote(s, usePlus=False) → str
Unquote(s, usePlus=False) → str
URLEncode(s) → str
StripTags(s) → str
DecodeHTMLEntities(s) → str
UUID() → str
StripDiacritics(s) → str
Pluralize(s) → str
LevenshteinDistance(a, b) → int
LevenshteinRatio(a, b) → float
LongestCommonSubstring(a, b) → str
CapitalizeWords(s) → str
ParseQueryString(s) → dict
ParseQueryStringAsList(s) → list[tuple]
SplitExtension(s) → tuple
Dedent(s) → str
Join(words, sep=None) → str
JoinURL(base, url) → str
Clean(s, form=’NFKD’, lang=None, strip_diacritics=False, strip_punctuation=False) → str
String Constants
Hash
MD5(data, digest=False) → str
SHA1(data, digest=False) → str
SHA224(data, digest=False) → str
SHA256(data, digest=False) → str
SHA384(data, digest=False) → str
SHA512(data, digest=False) → str
CRC32(data) → int
Regex
Regex Constants
Datetime
Now() → datetime
UTCNow() → datetime
ParseDate(date, fmt=None) → datetime
Delta(**kwargs) → timedelta
TimestampFromDatetime(dt) → int
FromTimestamp(ts) → datetime
MillisecondsFromString(s) → int
Archive
Zip(data=None) → ZipArchive
ZipFromURL(url, …) → ZipArchive
GzipCompress(data) → str
GzipDecompress(data) → str
AMF
RemotingService(*args, amf_version=3) → RemotingService
RegisterClass
SOL(*args) → SOL object
Util
Floor(x) → float
Ceiling(x) → float
VersionAtLeast(version_string, *components) → bool
ListSortedByKey(l, key) → list
ListSortedByAttr(l, attr) → list
SortListByKey(l, key)
SortListByAttr(l, attr)
LevenshteinDistance(a, b) → int
LongestCommonSubstring(a, b) → str
Random() → float
RandomInt(a, b) → int
RandomItemFromList(l) → any
RandomChoice(l) → any
RandomSample(l, count) → list
Logging API
Log
Log(fmt, *args)
Debug(fmt, *args)
Info(fmt, *args)
Warn(fmt, *args)
Error(fmt, *args)
Critical(fmt, *args)
Exception(fmt, *args)
Stack()
Locale & Localization API
Locale
DefaultLocale → str
CurrentLocale → str or None
Geolocation → str
Language
CountryCodes
L
F
Localization String Files
Resource API
ExternalPath(itemname) → str
Load(itemname, binary=True) → str
GuessMimeType(path) → str
AddMimeType(mimetype, extension)
ContentsOfURLWithFallback(url, fallback=None, hosted_fallback=None) → str
Hosted(type, group, identifier=None) → HostedResource
SharedExternalPath(itemname) → str
LoadShared(itemname, binary=True) → str
R
Threading API
Thread
Create(f, globalize=True, *args, **kwargs) → Thread
CreateTimer(interval, f, globalize=True, *args, **kwargs) → Timer
Sleep(interval)
Lock(key=None) → Lock
AcquireLock(key)
ReleaseLock(key)
Block(key)
Unblock(key)
Wait(key, timeout=None) → bool
Event(key=None) → Event
Semaphore(key=None, limit=1) → Semaphore
Queue
Decorator Examples
Cryptography API
Cipher
CBC
Rijndael
PadWithPadLen
Crypt
Helper API
Helper
Run(helper, *args) → str
Process(helper, *args, stderr=False) → Popen
Constants
Cache Time Constants
ClientPlatform
Protocol
AudioCodec
VideoCodec
Container (Constant)
ContainerContent
ViewType
SummaryTextType
StreamType
Runtime & Plugin API
Plugin
Identifier → str
Title → str
IconResourceName → str
ArtResourceName → str
TitleBarResourceName → str
Prefixes → list
ViewGroups → dict
Traceback(msg=’Traceback’)
Nice(value) → int
AddPrefixHandler(prefix, handler, name, thumb=None, art=None, titleBar=None, share=False)
AddViewGroup(name, viewMode=”List”, mediaType=”items”, type=None, menu=None, cols=None, rows=None, thumb=None, summary=None)
Client
Platform → str
Product → str
Version → str
Platform
OS → str
OSVersion → str
CPU → str
HasWebKit → bool
HasFlash → bool
HasSilverlight → bool
MachineIdentifier → str
ServerVersion → str
Request
Headers → dict
Body → str
Method → str
Response
Headers → dict
Status → int
Route
Connect(path, f, method=[‘GET’], allow_sync=False)
Plex Plugin Docs
Index
Edit on GitHub
Index