Table of Contents 

sonicallySimilar(limit: int | None = None, maxDistance: float | None = None, **kwargs) → List[TAudio][source]

Returns a list of sonically similar audio items.

Parameters:

limit (int) – Maximum count of items to return. Default 50 (server default)
maxDistance (float) – Maximum distance between tracks, 0.0 - 1.0. Default 0.25 (server default).
**kwargs – Additional options passed into fetchItems().

Returns:

list of sonically similar audio items.

Return type:

List[Audio]

class plexapi.audio.Artist(server, data, initpath=None, parent=None)[source]

Bases: Audio, AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, ArtistEditMixins

Represents a single Artist.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘artist’
albumSort (int) – Setting that indicates how albums are sorted for the artist (-1 = Library default, 0 = Newest first, 1 = Oldest first, 2 = By name).
collections (List<Collection>) – List of collection objects.
countries (List<Country>) – List country objects.
genres (List<Genre>) – List of genre objects.
guids (List<Guid>) – List of guid objects.
key (str) – API URL (/library/metadata/<ratingkey>).
labels (List<Label>) – List of label objects.
locations (List<str>) – List of folder paths where the artist is found on disk.
similar (List<Similar>) – List of similar objects.
styles (List<Style>) – List of style objects.
theme (str) – URL to theme resource (/library/metadata/<ratingkey>/theme/<themeid>).

album(title)[source]

Returns the Album that matches the specified title.

Parameters:: title (str) – Title of the album to return.

albums(**kwargs)[source]: Returns a list of Album objects by the artist.

track(title=None, album=None, track=None)[source]

Returns the Track that matches the specified title.

Parameters:

title (str) – Title of the track to return.
album (str) – Album name (default: None; required if title not specified).
track (int) – Track number (default: None; required if title not specified).

Raises:

BadRequest – If title or album and track parameters are missing.

tracks(**kwargs)[source]: Returns a list of Track objects by the artist.

get(title=None, album=None, track=None)[source]: Alias of track().

download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)[source]

Download all tracks from the artist. See download() for details.

Parameters:

savepath (str) – Defaults to current working dir.
keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated.
subfolders (bool) – True to separate tracks in to album folders.
**kwargs – Additional options passed into getStreamURL().

station()[source]: Returns a Playlist artist radio station or None.

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.audio.Album(server, data, initpath=None, parent=None)[source]

Bases: Audio, SplitMergeMixin, UnmatchMatchMixin, RatingMixin, ArtMixin, PosterMixin, ThemeUrlMixin, AlbumEditMixins

Represents a single Album.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘album’
collections (List<Collection>) – List of collection objects.
formats (List<Format>) – List of format objects.
genres (List<Genre>) – List of genre objects.
guids (List<Guid>) – List of guid objects.
key (str) – API URL (/library/metadata/<ratingkey>).
labels (List<Label>) – List of label objects.
leafCount (int) – Number of items in the album view.
loudnessAnalysisVersion (int) – The Plex loudness analysis version level.
originallyAvailableAt (datetime) – Datetime the album was released.
parentGuid (str) – Plex GUID for the album artist (plex://artist/5d07bcb0403c64029053ac4c).
parentKey (str) – API URL of the album artist (/library/metadata/<parentRatingKey>).
parentRatingKey (int) – Unique key identifying the album artist.
parentTheme (str) – URL to artist theme resource (/library/metadata/<parentRatingkey>/theme/<themeid>).
parentThumb (str) – URL to album artist thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
parentTitle (str) – Name of the album artist.
rating (float) – Album rating (7.9; 9.8; 8.1).
studio (str) – Studio that released the album.
styles (List<Style>) – List of style objects.
subformats (List<Subformat>) – List of subformat objects.
viewedLeafCount (int) – Number of items marked as played in the album view.
year (int) – Year the album was released.

track(title=None, track=None)[source]

Returns the Track that matches the specified title.

Parameters:

title (str) – Title of the track to return.
track (int) – Track number (default: None; required if title not specified).

Raises:

BadRequest – If title or track parameter is missing.

tracks(**kwargs)[source]: Returns a list of Track objects in the album.

get(title=None, track=None)[source]: Alias of track().

artist()[source]: Return the album’s Artist.

download(savepath=None, keep_original_name=False, **kwargs)[source]

Download all tracks from the album. See download() for details.

Parameters:

savepath (str) – Defaults to current working dir.
keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated.
**kwargs – Additional options passed into getStreamURL().

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.audio.Track(server, data, initpath=None, parent=None)[source]

Bases: Audio, Playable, ExtrasMixin, RatingMixin, ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin, TrackEditMixins

Represents a single Track.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘track’
chapters (List<Chapter>) – List of Chapter objects.
chapterSource (str) – Unknown
collections (List<Collection>) – List of collection objects.
duration (int) – Length of the track in milliseconds.
genres (List<Genre>) – List of genre objects.
grandparentArt (str) – URL to album artist artwork (/library/metadata/<grandparentRatingKey>/art/<artid>).
grandparentGuid (str) – Plex GUID for the album artist (plex://artist/5d07bcb0403c64029053ac4c).
grandparentKey (str) – API URL of the album artist (/library/metadata/<grandparentRatingKey>).
grandparentRatingKey (int) – Unique key identifying the album artist.
grandparentTheme (str) – URL to artist theme resource (/library/metadata/<grandparentRatingkey>/theme/<themeid>). (/library/metadata/<grandparentRatingkey>/theme/<themeid>).
grandparentThumb (str) – URL to album artist thumbnail image (/library/metadata/<grandparentRatingKey>/thumb/<thumbid>).
grandparentTitle (str) – Name of the album artist for the track.
guids (List<Guid>) – List of guid objects.
labels (List<Label>) – List of label objects.
media (List<Media>) – List of media objects.
originalTitle (str) – The artist for the track.
parentGuid (str) – Plex GUID for the album (plex://album/5d07cd8e403c640290f180f9).
parentIndex (int) – Disc number of the track.
parentKey (str) – API URL of the album (/library/metadata/<parentRatingKey>).
parentRatingKey (int) – Unique key identifying the album.
parentThumb (str) – URL to album thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
parentTitle (str) – Name of the album for the track.
primaryExtraKey (str) –
ratingCount (int) – Number of listeners who have scrobbled this track, as reported by Last.fm.
skipCount (int) – Number of times the track has been skipped.
sourceURI (str) – Remote server URI (server://<machineIdentifier>/com.plexapp.plugins.library) (remote playlist item only).
viewOffset (int) – View offset in milliseconds.
year (int) – Year the track was released.

property locations

This does not exist in plex xml response but is added to have a common interface to get the locations of the track.

Returns:: List<str> of file paths where the track is found on disk.

property trackNumber: Returns the track number.

album()[source]: Return the track’s Album.

artist()[source]: Return the track’s Artist.

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

sonicAdventure(to: TTrack, **kwargs: Any) → list[TTrack][source]

Returns a sonic adventure from the current track to the specified track.

Parameters:

to (Track) – The target track for the sonic adventure.
**kwargs – Additional options passed into sonicAdventure().

Returns:

list of tracks in the sonic adventure.

Return type:

List[Track]

class plexapi.audio.TrackSession(server, data, initpath=None, parent=None)[source]

Bases: PlexSession, Track

Represents a single Track session loaded from sessions().

class plexapi.audio.TrackHistory(server, data, initpath=None, parent=None)[source]

Bases: PlexHistory, Track

Represents a single Track history entry loaded from history().

Base plexapi.base

class plexapi.base.PlexObject(server, data, initpath=None, parent=None)[source]

Bases: object

Base class for all Plex objects.

Parameters:

server (PlexServer) – PlexServer this client is connected to (optional)
data (ElementTree) – Response from PlexServer used to build this object (optional).
initpath (str) – Relative path requested when retrieving specified data (optional).
parent (PlexObject) – The parent object that this object is built from (optional).

fetchItems(ekey, cls=None, container_start=None, container_size=None, maxresults=None, params=None, **kwargs)[source]

Load the specified key to find and build all items with the specified tag and attrs.

Parameters:

ekey (str or List<int>) – API URL path in Plex to fetch items from. If a list of ints is passed in, the key will be translated to /library/metadata/<key1,key2,key3>. This allows fetching multiple items only knowing their key-ids.
cls (PlexObject) – If you know the class of the items to be fetched, passing this in will help the parser ensure it only returns those items. By default we convert the xml elements with the best guess PlexObjects based on tag and type attrs.
etag (str) – Only fetch items with the specified tag.
container_start (None, int) – offset to get a subset of the data
container_size (None, int) – How many items in data
maxresults (int, optional) – Only return the specified number of results.
params (dict, optional) – Any additional params to add to the request.
**kwargs (dict) – Optionally add XML attribute to filter the items. See the details below for more info.

Filtering XML Attributes

Any XML attribute can be filtered when fetching results. Filtering is done before the Python objects are built to help keep things speedy. For example, passing in viewCount=0 will only return matching items where the view count is 0. Note that case matters when specifying attributes. Attributes further down in the XML tree can be filtered by prepending the attribute with each element tag Tag__.

Examples

fetchItem(ekey, viewCount=0)
fetchItem(ekey, contentRating="PG")
fetchItem(ekey, Genre__tag="Animation")
fetchItem(ekey, Media__videoCodec="h265")
fetchItem(ekey, Media__Part__container="mp4)

Note that because some attribute names are already used as arguments to this function, such as tag, you may still reference the attr tag by prepending an underscore. For example, passing in _tag='foobar' will return all items where tag='foobar'.

Using PlexAPI Operators

Optionally, PlexAPI operators can be specified by appending it to the end of the attribute for more complex lookups. For example, passing in viewCount__gte=0 will return all items where viewCount >= 0.

List of Available Operators:

__contains: Value contains specified arg.
__endswith: Value ends with specified arg.
__exact: Value matches specified arg.
__exists (bool): Value is or is not present in the attrs.
__gt: Value is greater than specified arg.
__gte: Value is greater than or equal to specified arg.
__icontains: Case insensitive value contains specified arg.
__iendswith: Case insensitive value ends with specified arg.
__iexact: Case insensitive value matches specified arg.
__in: Value is in a specified list or tuple.
__iregex: Case insensitive value matches the specified regular expression.
__istartswith: Case insensitive value starts with specified arg.
__lt: Value is less than specified arg.
__lte: Value is less than or equal to specified arg.
__regex: Value matches the specified regular expression.
__startswith: Value starts with specified arg.

Examples

fetchItem(ekey, viewCount__gte=0)
fetchItem(ekey, Media__container__in=["mp4", "mkv"])
fetchItem(ekey, guid__regex=r"com\.plexapp\.agents\.(imdb|themoviedb)://|tt\d+")
fetchItem(ekey, guid__id__regex=r"(imdb|tmdb|tvdb)://")
fetchItem(ekey, Media__Part__file__startswith="D:\Movies")

fetchItem(ekey, cls=None, **kwargs)[source]

Load the specified key to find and build the first item with the specified tag and attrs. If no tag or attrs are specified then the first item in the result set is returned.

Parameters:

ekey (str or int) – Path in Plex to fetch items from. If an int is passed in, the key will be translated to /library/metadata/<key>. This allows fetching an item only knowing its key-id.
cls (PlexObject) – If you know the class of the items to be fetched, passing this in will help the parser ensure it only returns those items. By default we convert the xml elements with the best guess PlexObjects based on tag and type attrs.
etag (str) – Only fetch items with the specified tag.
**kwargs (dict) – Optionally add XML attribute to filter the items. See fetchItems() for more details on how this is used.

findItems(data, cls=None, initpath=None, rtag=None, **kwargs)[source]: Load the specified data to find and build all items with the specified tag and attrs. See fetchItem() for more details on how this is used.

findItem(data, cls=None, initpath=None, rtag=None, **kwargs)[source]: Load the specified data to find and build the first items with the specified tag and attrs. See fetchItem() for more details on how this is used.

firstAttr(*attrs)[source]: Return the first attribute in attrs that is not None.

listAttrs(data, attr, rtag=None, **kwargs)[source]: Return a list of values from matching attribute.

reload(key=None, **kwargs)[source]

Reload the data for this object from self.key.

Parameters:

key (string, optional) – Override the key to reload.
**kwargs (dict) – A dictionary of XML include parameters to exclude or override. All parameters are included by default with the option to override each parameter or disable each parameter individually by setting it to False or 0. See PlexPartialObject for all the available include parameters.

Example

from plexapi.server import PlexServer
plex = PlexServer('http://localhost:32400', token='xxxxxxxxxxxxxxxxxxxx')
movie = plex.library.section('Movies').get('Cars')

# Partial reload of the movie without the `checkFiles` parameter.
# Excluding `checkFiles` will prevent the Plex server from reading the
# file to check if the file still exists and is accessible.
# The movie object will remain as a partial object.
movie.reload(checkFiles=False)
movie.isPartialObject()  # Returns True

# Full reload of the movie with all include parameters.
# The movie object will be a full object.
movie.reload()
movie.isFullObject()  # Returns True

class plexapi.base.PlexPartialObject(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Not all objects in the Plex listings return the complete list of elements for the object. This object will allow you to assume each object is complete, and if the specified value you request is None it will fetch the full object automatically and update itself.

analyze()[source]

Tell Plex Media Server to performs analysis on it this item to gather information. Analysis includes:

Gather Media Properties: All of the media you add to a Library has
properties that are useful to know–whether it’s a video file, a music track, or one of your photos (container, codec, resolution, etc).
Generate Default Artwork: Artwork will automatically be grabbed from a
video file. A background image will be pulled out as well as a smaller image to be used for poster/thumbnail type purposes.
Generate Video Preview Thumbnails: Video preview thumbnails are created,
if you have that feature enabled. Video preview thumbnails allow graphical seeking in some Apps. It’s also used in the Plex Web App Now Playing screen to show a graphical representation of where playback is. Video preview thumbnails creation is a CPU-intensive process akin to transcoding the file.
Generate intro video markers: Detects show intros, exposing the
‘Skip Intro’ button in clients.

isFullObject()[source]: Returns True if this is already a full object. A full object means all attributes were populated from the api path representing only this item. For example, the search result for a movie often only contain a portion of the attributes a full object (main url) for that movie would contain.

isPartialObject()[source]: Returns True if this is not a full object.

isLocked(field: str)[source]

Returns True if the specified field is locked, otherwise False.

Parameters:: field (str) – The name of the field.

edit(**kwargs)[source]

Edit an object. Note: This is a low level method and you need to know all the field/tag keys. See EditFieldMixin and EditTagsMixin for individual field and tag editing methods.

Parameters:: kwargs (dict) – Dict of settings to edit.

Example

edits = {
    'type': 1,
    'id': movie.ratingKey,
    'title.value': 'A new title',
    'title.locked': 1,
    'summary.value': 'This is a summary.',
    'summary.locked': 1,
    'collection[0].tag.tag': 'A tag',
    'collection.locked': 1}
}
movie.edit(**edits)

batchEdits()[source]

Enable batch editing mode to save API calls. Must call saveEdits() at the end to save all the edits. See EditFieldMixin and EditTagsMixin for individual field and tag editing methods.

Example

# Batch editing multiple fields and tags in a single API call
Movie.batchEdits()
Movie.editTitle('A New Title').editSummary('A new summary').editTagline('A new tagline') \
    .addCollection('New Collection').removeGenre('Action').addLabel('Favorite')
Movie.saveEdits()

saveEdits()[source]: Save all the batch edits. The object needs to be reloaded manually, if required. See batchEdits() for details.

refresh()[source]

Refreshing a Library or individual item causes the metadata for the item to be refreshed, even if it already has metadata. You can think of refreshing as “update metadata for the requested item even if it already has some”. You should refresh a Library or individual item if:

You’ve changed the Library Metadata Agent.
You’ve added “Local Media Assets” (such as artwork, theme music, external
subtitle files, etc.)
You want to freshen the item posters, summary, etc.
There’s a problem with the poster image that’s been downloaded.
Items are missing posters or other downloaded information. This is possible if
the refresh process is interrupted (the Server is turned off, internet connection dies, etc).

section()[source]: Returns the LibrarySection this item belongs to.

delete()[source]: Delete a media element. This has to be enabled under settings > server > library in plex webui.

history(maxresults=None, mindate=None)[source]

Get Play History for a media item.

Parameters:

maxresults (int) – Only return the specified number of results (optional).
mindate (datetime) – Min datetime to return results from.

getWebURL(base=None)[source]

Returns the Plex Web URL for a media item.

Parameters:: base (str) – The base URL before the fragment (#!). Default is https://app.plex.tv/desktop.

playQueue(*args, **kwargs)[source]: Returns a new PlayQueue from this media item. See create() for available parameters.

class plexapi.base.Playable[source]

Bases: object

This is a general place to store functions specific to media that is Playable. Things were getting mixed up a bit when dealing with Shows, Season, Artists, Albums which are all not playable.

Variables:

playlistItemID (int) – Playlist item ID (only populated for Playlist items).
playQueueItemID (int) – PlayQueue item ID (only populated for PlayQueue items).

getStreamURL(**kwargs)[source]

Returns a stream url that may be used by external applications such as VLC.

Parameters:: **kwargs (dict) – optional parameters to manipulate the playback when accessing the stream. A few known parameters include: maxVideoBitrate, videoResolution offset, copyts, protocol, mediaIndex, partIndex, platform.
Raises:: Unsupported – When the item doesn’t support fetching a stream URL.

iterParts()[source]: Iterates over the parts of this media item.

videoStreams()[source]: Returns a list of videoStream objects for all MediaParts.

audioStreams()[source]: Returns a list of AudioStream objects for all MediaParts.

subtitleStreams()[source]: Returns a list of SubtitleStream objects for all MediaParts.

lyricStreams()[source]: Returns a list of LyricStream objects for all MediaParts.

play(client)[source]

Start playback on the specified client.

Parameters:: client (PlexClient) – Client to start playing on.

download(savepath=None, keep_original_name=False, **kwargs)[source]

Downloads the media item to the specified location. Returns a list of filepaths that have been saved to disk.

Parameters:

savepath (str) – Defaults to current working dir.
keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated. See filenames below.
**kwargs (dict) – Additional options passed into getStreamURL() to download a transcoded stream, otherwise the media item will be downloaded as-is and saved to disk.

Filenames

Movie: <title> (<year>)
Episode: <show title> - s00e00 - <episode title>
Track: <artist title> - <album title> - 00 - <track title>
Photo: <photoalbum title> - <photo/clip title> or <photo/clip title>

updateProgress(time, state='stopped')[source]

Set the watched progress for this video.

Note that setting the time to 0 will not work. Use markPlayed() or markUnplayed() to achieve that goal.

Parameters:

time (int) – milliseconds watched
state (string) – state of the video, default ‘stopped’

updateTimeline(time, state='stopped', duration=None)[source]

Set the timeline progress for this video.

Parameters:

time (int) – milliseconds watched
state (string) – state of the video, default ‘stopped’
duration (int) – duration of the item

class plexapi.base.PlexSession[source]

Bases: object

This is a general place to store functions specific to media that is a Plex Session.

Variables:

live (bool) – True if this is a live tv session.
player (PlexClient) – PlexClient object for the session.
session (Session) – Session object for the session if the session is using bandwidth (None otherwise).
sessionKey (int) – The session key for the session.
transcodeSession (TranscodeSession) – TranscodeSession object if item is being transcoded (None otherwise).

property user: Returns the MyPlexAccount object (for admin) or MyPlexUser object (for users) for this session.

reload()[source]: Reload the data for the session. Note: This will return the object as-is if the session is no longer active.

source()[source]: Return the source media object for the session.

stop(reason='')[source]

Stop playback for the session.

Parameters:: reason (str) – Message displayed to the user for stopping playback.

class plexapi.base.PlexHistory[source]

Bases: object

This is a general place to store functions specific to media that is a Plex history item.

Variables:

accountID (int) – The associated SystemAccount ID.
deviceID (int) – The associated SystemDevice ID.
historyKey (str) – API URL (/status/sessions/history/<historyID>).
viewedAt (datetime) – Datetime item was last watched.

source()[source]: Return the source media object for the history entry or None if the media no longer exists on the server.

delete()[source]: Delete the history entry.

class plexapi.base.MediaContainer(server: PlexServer, data: Element, *args: PlexObjectT, initpath: str | None = None, parent: PlexObject | None = None)[source]

Bases: Generic[PlexObjectT], List[PlexObjectT], PlexObject

Represents a single MediaContainer.

Variables:

TAG (str) – ‘MediaContainer’
allowSync (int) – Sync/Download is allowed/disallowed for feature.
augmentationKey (str) – API URL (/library/metadata/augmentations/<augmentationKey>).
identifier (str) – “com.plexapp.plugins.library”
librarySectionID (int) – LibrarySection ID.
librarySectionTitle (str) – LibrarySection title.
librarySectionUUID (str) – LibrarySection UUID.
mediaTagPrefix (str) – “/system/bundle/media/flags/”
mediaTagVersion (int) – Unknown
offset (int) – The offset of current results.
size (int) – The number of items in the hub.
totalSize (int) – The total number of items for the query.

extend(_MediaContainer__iterable: Iterable[PlexObjectT] | MediaContainerT) → None[source]: Extend list by appending elements from the iterable.

Client plexapi.client

class plexapi.client.PlexClient(server=None, data=None, initpath=None, baseurl=None, identifier=None, token=None, connect=True, session=None, timeout=None, parent=None)[source]

Bases: PlexObject

Main class for interacting with a Plex client. This class can connect directly to the client and control it or proxy commands through your Plex Server. To better understand the Plex client API’s read this page: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API

Parameters:

server (PlexServer) – PlexServer this client is connected to (optional).
data (ElementTree) – Response from PlexServer used to build this object (optional).
initpath (str) – Path used to generate data.
baseurl (str) – HTTP URL to connect directly to this client.
identifier (str) – The resource/machine identifier for the desired client. May be necessary when connecting to a specific proxied client (optional).
token (str) – X-Plex-Token used for authentication (optional).
session (Session) – requests.Session object if you want more control (optional).
timeout (int) – timeout in seconds on initial connect to client (default config.TIMEOUT).

Variables:

TAG (str) – ‘Player’
key (str) – ‘/resources’
device (str) – Best guess on the type of device this is (PS, iPhone, Linux, etc).
deviceClass (str) – Device class (pc, phone, etc).
machineIdentifier (str) – Unique ID for this device.
model (str) – Unknown
platform (str) – Unknown
platformVersion (str) – Description
product (str) – Client Product (Plex for iOS, etc).
protocol (str) – Always seems ot be ‘plex’.
protocolCapabilities (list<str>) – List of client capabilities (navigation, playback, timeline, mirror, playqueues).
protocolVersion (str) – Protocol version (1, future proofing?)
server (PlexServer) – Server this client is connected to.
session (Session) – Session object used for connection.
state (str) – Unknown
title (str) – Name of this client (Johns iPhone, etc).
token (str) – X-Plex-Token used for authentication
vendor (str) – Unknown
version (str) – Device version (4.6.1, etc).
_baseurl (str) – HTTP address of the client.
_token (str) – Token used to access this client.
_session (obj) – Requests session object used to access this client.
_proxyThroughServer (bool) – Set to True after calling proxyThroughServer() (default False).

connect(timeout=None)[source]: Alias of reload as any subsequent requests to this client will be made directly to the device even if the object attributes were initially populated from a PlexServer.

reload()[source]: Alias to self.connect().

proxyThroughServer(value=True, server=None)[source]

Tells this PlexClient instance to proxy all future commands through the PlexServer. Useful if you do not wish to connect directly to the Client device itself.

Parameters:: value (bool) – Enable or disable proxying (optional, default True).
Raises:: Unsupported – Cannot use client proxy with unknown server.

query(path, method=None, headers=None, timeout=None, **kwargs)[source]: Main method used to handle HTTPS requests to the Plex client. This method helps by encoding the response to utf-8 and parsing the returned XML into and ElementTree object. Returns None if no data exists in the response.

sendCommand(command, proxy=None, **params)[source]

Convenience wrapper around query() to more easily send simple commands to the client. Returns an ElementTree object containing the response.

Parameters:

command (str) – Command to be sent in for format ‘<controller>/<command>’.
proxy (bool) – Set True to proxy this command through the PlexServer.
**params (dict) – Additional GET parameters to include with the command.

Raises:

Unsupported – When we detect the client doesn’t support this capability.

url(key, includeToken=False)[source]: Build a URL string with proper token argument. Token will be appended to the URL if either includeToken is True or CONFIG.log.show_secrets is ‘true’.

contextMenu()[source]: Open the context menu on the client.

goBack()[source]: Navigate back one position.

goToHome()[source]: Go directly to the home screen.

goToMusic()[source]: Go directly to the playing music panel.

moveDown()[source]: Move selection down a position.

moveLeft()[source]: Move selection left a position.

moveRight()[source]: Move selection right a position.

moveUp()[source]: Move selection up a position.

nextLetter()[source]: Jump to next letter in the alphabet.

pageDown()[source]: Move selection down a full page.

pageUp()[source]: Move selection up a full page.

previousLetter()[source]: Jump to previous letter in the alphabet.

select()[source]: Select element at the current position.

toggleOSD()[source]: Toggle the on screen display during playback.

goToMedia(media, **params)[source]

Navigate directly to the specified media page.

Parameters:

media (Media) – Media object to navigate to.
**params (dict) – Additional GET parameters to include with the command.

pause(mtype='video')[source]

Pause the currently playing media type.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

play(mtype='video')[source]

Start playback for the specified media type.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

refreshPlayQueue(playQueueID, mtype='video')[source]

Refresh the specified Playqueue.

Parameters:

playQueueID (str) – Playqueue ID.
mtype (str) – Media type to take action against (music, photo, video).

seekTo(offset, mtype='video')[source]

Seek to the specified offset (ms) during playback.

Parameters:

offset (int) – Position to seek to (milliseconds).
mtype (str) – Media type to take action against (music, photo, video).

skipNext(mtype='video')[source]

Skip to the next playback item.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

skipPrevious(mtype='video')[source]

Skip to previous playback item.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

skipTo(key, mtype='video')[source]

Skip to the playback item with the specified key.

Parameters:

key (str) – Key of the media item to skip to.
mtype (str) – Media type to take action against (music, photo, video).

stepBack(mtype='video')[source]

Step backward a chunk of time in the current playback item.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

stepForward(mtype='video')[source]

Step forward a chunk of time in the current playback item.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

stop(mtype='video')[source]

Stop the currently playing item.

Parameters:: mtype (str) – Media type to take action against (music, photo, video).

setRepeat(repeat, mtype='video')[source]

Enable repeat for the specified playback items.

Parameters:

repeat (int) – Repeat mode (0=off, 1=repeatone, 2=repeatall).
mtype (str) – Media type to take action against (music, photo, video).

setShuffle(shuffle, mtype='video')[source]

Enable shuffle for the specified playback items.

Parameters:

shuffle (int) – Shuffle mode (0=off, 1=on)
mtype (str) – Media type to take action against (music, photo, video).

setVolume(volume, mtype='video')[source]

Enable volume for the current playback item.

Parameters:

volume (int) – Volume level (0-100).
mtype (str) – Media type to take action against (music, photo, video).

setAudioStream(audioStreamID, mtype='video')[source]

Select the audio stream for the current playback item (only video).

Parameters:

audioStreamID (str) – ID of the audio stream from the media object.
mtype (str) – Media type to take action against (music, photo, video).

setSubtitleStream(subtitleStreamID, mtype='video')[source]

Select the subtitle stream for the current playback item (only video).

Parameters:

subtitleStreamID (str) – ID of the subtitle stream from the media object.
mtype (str) – Media type to take action against (music, photo, video).

setVideoStream(videoStreamID, mtype='video')[source]

Select the video stream for the current playback item (only video).

Parameters:

videoStreamID (str) – ID of the video stream from the media object.
mtype (str) – Media type to take action against (music, photo, video).

playMedia(media, offset=0, **params)[source]

Start playback of the specified media item. See also:

Parameters:

media (Media) – Media item to be played back (movie, music, photo, playlist, playqueue).
offset (int) – Number of milliseconds at which to start playing with zero representing the beginning (default 0).
**params (dict) – Optional additional parameters to include in the playback request. See also: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API#modified-commands

setParameters(volume=None, shuffle=None, repeat=None, mtype='video')[source]

Set multiple playback parameters at once.

Parameters:

volume (int) – Volume level (0-100; optional).
shuffle (int) – Shuffle mode (0=off, 1=on; optional).
repeat (int) – Repeat mode (0=off, 1=repeatone, 2=repeatall; optional).
mtype (str) – Media type to take action against (optional music, photo, video).

setStreams(audioStreamID=None, subtitleStreamID=None, videoStreamID=None, mtype='video')[source]

Select multiple playback streams at once.

Parameters:

audioStreamID (str) – ID of the audio stream from the media object.
subtitleStreamID (str) – ID of the subtitle stream from the media object.
videoStreamID (str) – ID of the video stream from the media object.
mtype (str) – Media type to take action against (optional music, photo, video).

timelines(wait=0)[source]: Poll the client’s timelines, create, and return timeline objects. Some clients may not always respond to timeline requests, believe this to be a Plex bug.

property timeline: Returns the active timeline object.

isPlayingMedia(includePaused=True)[source]

Returns True if any media is currently playing.

Parameters:: includePaused (bool) – Set True to treat currently paused items as playing (optional; default True).

class plexapi.client.ClientTimeline(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Get the timeline’s attributes.

Collection plexapi.collection

class plexapi.collection.Collection(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, CollectionEditMixins

Represents a single Collection.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘collection’
addedAt (datetime) – Datetime the collection was added to the library.
art (str) – URL to artwork image (/library/metadata/<ratingKey>/art/<artid>).
artBlurHash (str) – BlurHash string for artwork image.
childCount (int) – Number of items in the collection.
collectionFilterBasedOnUser (int) – Which user’s activity is used for the collection filtering.
collectionMode (int) – How the items in the collection are displayed.
collectionPublished (bool) – True if the collection is published to the Plex homepage.
collectionSort (int) – How to sort the items in the collection.
content (str) – The filter URI string for smart collections.
contentRating (str) Content rating (PG-13; NR; TV-G) –
fields (List<Field>) – List of field objects.
guid (str) – Plex GUID for the collection (collection://XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX).
index (int) – Plex index number for the collection.
key (str) – API URL (/library/metadata/<ratingkey>).
labels (List<Label>) – List of label objects.
lastRatedAt (datetime) – Datetime the collection was last rated.
librarySectionID (int) – LibrarySection ID.
librarySectionKey (str) – LibrarySection key.
librarySectionTitle (str) – LibrarySection title.
maxYear (int) – Maximum year for the items in the collection.
minYear (int) – Minimum year for the items in the collection.
ratingCount (int) – The number of ratings.
ratingKey (int) – Unique key identifying the collection.
smart (bool) – True if the collection is a smart collection.
subtype (str) – Media type of the items in the collection (movie, show, artist, or album).
summary (str) – Summary of the collection.
theme (str) – URL to theme resource (/library/metadata/<ratingkey>/theme/<themeid>).
thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
thumbBlurHash (str) – BlurHash string for thumbnail image.
title (str) – Name of the collection.
titleSort (str) – Title to use when sorting (defaults to title).
type (str) – ‘collection’
updatedAt (datetime) – Datetime the collection was updated.
userRating (float) – Rating of the collection (0.0 - 10.0) equaling (0 stars - 5 stars).

property listType: Returns the listType for the collection.

property metadataType: Returns the type of metadata in the collection.

property isVideo: Returns True if this is a video collection.

property isAudio: Returns True if this is an audio collection.

property isPhoto: Returns True if this is a photo collection.

filters()[source]: Returns the search filter dict for smart collection. The filter dict be passed back into search() to get the list of items.

section()[source]: Returns the LibrarySection this collection belongs to.

item(title)[source]

Returns the item in the collection that matches the specified title.

Parameters:: title (str) – Title of the item to return.
Raises:: plexapi.exceptions.NotFound – When the item is not found in the collection.

items()[source]: Returns a list of all items in the collection.

visibility()[source]: Returns the ManagedHub for this collection.

get(title)[source]: Alias to item().

filterUserUpdate(user=None)[source]

Update the collection filtering user advanced setting.

Parameters:: user (str) – One of the following values: “admin” (Always the server admin user), “user” (User currently viewing the content)

Example

collection.updateMode(user="user")

modeUpdate(mode=None)[source]

Update the collection mode advanced setting.

Parameters:: mode (str) – One of the following values: “default” (Library default), “hide” (Hide Collection), “hideItems” (Hide Items in this Collection), “showItems” (Show this Collection and its Items)

Example

collection.updateMode(mode="hide")

sortUpdate(sort=None)[source]

Update the collection order advanced setting.

Parameters:: sort (str) – One of the following values: “release” (Order Collection by release dates), “alpha” (Order Collection alphabetically), “custom” (Custom collection order)

Example

collection.sortUpdate(sort="alpha")

addItems(items)[source]

Add items to the collection.

Parameters:: items (List) – List of Audio, Video, or Photo objects to be added to the collection.
Raises:: plexapi.exceptions.BadRequest – When trying to add items to a smart collection.

removeItems(items)[source]

Remove items from the collection.

Parameters:: items (List) – List of Audio, Video, or Photo objects to be removed from the collection.
Raises:: plexapi.exceptions.BadRequest – When trying to remove items from a smart collection.

moveItem(item, after=None)[source]

Move an item to a new position in the collection.

Parameters:

item (obj) – Audio, Video, or Photo object to be moved in the collection.
after (obj) – Audio, Video, or Photo object to move the item after in the collection.

Raises:

plexapi.exceptions.BadRequest – When trying to move items in a smart collection.

updateFilters(libtype=None, limit=None, sort=None, filters=None, **kwargs)[source]

Update the filters for a smart collection.

Parameters:

libtype (str) – The specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).
limit (int) – Limit the number of items in the collection.
sort (str or list, optional) – A string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – A dictionary of advanced filters. See search() for more info.
**kwargs (dict) – Additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When trying update filters for a regular collection.

edit(title=None, titleSort=None, contentRating=None, summary=None, **kwargs)[source]

Edit the collection.

Parameters:

title (str, optional) – The title of the collection.
titleSort (str, optional) – The sort title of the collection.
contentRating (str, optional) – The summary of the collection.
summary (str, optional) – The summary of the collection.

delete()[source]: Delete the collection.

classmethod create(server, title, section, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs)[source]

Create a collection.

Parameters:

server (PlexServer) – Server to create the collection on.
title (str) – Title of the collection.
section (LibrarySection, str) – The library section to create the collection in.
items (List) – Regular collections only, list of Audio, Video, or Photo objects to be added to the collection.
smart (bool) – True to create a smart collection. Default False.
limit (int) – Smart collections only, limit the number of items in the collection.
libtype (str) – Smart collections only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).
sort (str or list, optional) – Smart collections only, a string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – Smart collections only, a dictionary of advanced filters. See search() for more info.
**kwargs (dict) – Smart collections only, additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When no items are included to create the collection.
plexapi.exceptions.BadRequest – When mixing media types in the collection.

Returns:

A new instance of the created Collection.

Return type:

Collection

sync(videoQuality=None, photoResolution=None, audioBitrate=None, client=None, clientId=None, limit=None, unwatched=False, title=None)[source]

Add the collection as sync item for the specified device. See sync() for possible exceptions.

Parameters:

videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module. Used only when collection contains video.
photoResolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync. Used only when collection contains photos.
audioBitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync. Used only when collection contains audio.
client (MyPlexDevice) – sync destination, see sync().
clientId (str) – sync destination, see sync().
limit (int) – maximum count of items to sync, unlimited if None.
unwatched (bool) – if True watched videos wouldn’t be synced.
title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current photo.

Raises:

BadRequest – When collection is not allowed to sync.
Unsupported – When collection content is unsupported.

Returns:

A new instance of the created sync item.

Return type:

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

Config plexapi.config

class plexapi.config.PlexConfig(path)[source]

Bases: ConfigParser

PlexAPI configuration object. Settings are stored in an INI file within the user’s home directory and can be overridden after importing plexapi by simply setting the value. See the documentation section ‘Configuration’ for more details on available options.

Parameters:: path (str) – Path of the configuration file to load.

get(key, default=None, cast=None)[source]

Returns the specified configuration value or <default> if not found.

Parameters:

key (str) – Configuration variable to load in the format ‘<section>.<variable>’.
default – Default value to use if key not found.
cast (func) – Cast the value to the specified type before returning.

plexapi.config.reset_base_headers()[source]: Convenience function returns a dict of all base X-Plex-* headers for session requests.

Exceptions plexapi.exceptions

exception plexapi.exceptions.PlexApiException[source]

Bases: Exception

Base class for all PlexAPI exceptions.

exception plexapi.exceptions.BadRequest[source]

An invalid request, generally a user error.

exception plexapi.exceptions.NotFound[source]

Request media item or device is not found.

exception plexapi.exceptions.UnknownType[source]

Unknown library type.

exception plexapi.exceptions.Unsupported[source]

Unsupported client request.

exception plexapi.exceptions.Unauthorized[source]

Bases: BadRequest

Invalid username/password or token.

exception plexapi.exceptions.TwoFactorRequired[source]

Bases: Unauthorized

Two factor authentication required.

Gdm plexapi.gdm

Support for discovery using GDM (Good Day Mate), multicast protocol by Plex.

# Licensed Apache 2.0 # From https://github.com/home-assistant/netdisco/netdisco/gdm.py

Inspired by:: hippojay’s plexGDM: https://github.com/hippojay/script.plexbmc.helper/resources/lib/plexgdm.py iBaa’s PlexConnect: https://github.com/iBaa/PlexConnect/PlexAPI.py

class plexapi.gdm.GDM[source]

Bases: object

Base class to discover GDM services.

Variables:: entries (List<dict>) – List of server and/or client data discovered.

scan(scan_for_clients=False)[source]: Scan the network.

all(scan_for_clients=False)[source]

Return all found entries.

Will scan for entries if not scanned recently.

find_by_content_type(value)[source]: Return a list of entries that match the content_type.

find_by_data(values)[source]: Return a list of entries that match the search parameters.

update(scan_for_clients)[source]

Scan for new GDM services.

Examples of the dict list assigned to self.entries by this function:

Server:

[{‘data’: {
‘Content-Type’: ‘plex/media-server’, ‘Host’: ‘53f4b5b6023d41182fe88a99b0e714ba.plex.direct’, ‘Name’: ‘myfirstplexserver’, ‘Port’: ‘32400’, ‘Resource-Identifier’: ‘646ab0aa8a01c543e94ba975f6fd6efadc36b7’, ‘Updated-At’: ‘1585769946’, ‘Version’: ‘1.18.8.2527-740d4c206’,

},
‘from’: (‘10.10.10.100’, 32414)}]

Clients:

[{‘data’: {‘Content-Type’: ‘plex/media-player’,
‘Device-Class’: ‘stb’, ‘Name’: ‘plexamp’, ‘Port’: ‘36000’, ‘Product’: ‘Plexamp’, ‘Protocol’: ‘plex’, ‘Protocol-Capabilities’: ‘timeline,playback,playqueues,playqueues-creation’, ‘Protocol-Version’: ‘1’, ‘Resource-Identifier’: ‘b6e57a3f-e0f8-494f-8884-f4b58501467e’, ‘Version’: ‘1.1.0’,

},
‘from’: (‘10.10.10.101’, 32412)}]

plexapi.gdm.main()[source]: Test GDM discovery.

Library plexapi.library

class plexapi.library.Library(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a PlexServer library. This contains all sections of media defined in your Plex server including video, shows and audio.

Variables:

key (str) – ‘/library’
identifier (str) – Unknown (‘com.plexapp.plugins.library’).
mediaTagVersion (str) – Unknown (/system/bundle/media/flags/)
server (PlexServer) – PlexServer this client is connected to.
title1 (str) – ‘Plex Library’ (not sure how useful this is).
title2 (str) – Second title (this is blank on my setup).

sections()[source]: Returns a list of all media sections in this library. Library sections may be any of MovieSection, ShowSection, MusicSection, PhotoSection.

section(title)[source]

Returns the LibrarySection that matches the specified title. Note: Multiple library sections with the same title is ambiguous. Use sectionByID() instead for an exact match.

Parameters:: title (str) – Title of the section to return.
Raises:: NotFound – The library section title is not found on the server.

sectionByID(sectionID)[source]

Returns the LibrarySection that matches the specified sectionID.

Parameters:: sectionID (int) – ID of the section to return.
Raises:: NotFound – The library section ID is not found on the server.

hubs(sectionID=None, identifier=None, **kwargs)[source]

Returns a list of Hub across all library sections.

Parameters:

sectionID (int or str or list, optional) – IDs of the sections to limit results or “playlists”.
identifier (str or list, optional) – Names of identifiers to limit results. Available on Hub instances as the hubIdentifier attribute. Examples: ‘home.continue’ or ‘home.ondeck’

all(**kwargs)[source]: Returns a list of all media from all library sections. This may be a very large dataset to retrieve.

onDeck()[source]: Returns a list of all media items on deck.

recentlyAdded()[source]: Returns a list of all media items recently added.

search(title=None, libtype=None, **kwargs)[source]

Searching within a library section is much more powerful. It seems certain attributes on the media objects can be targeted to filter this search down a bit, but I haven’t found the documentation for it.

Example: “studio=Comedy%20Central” or “year=1999” “title=Kung Fu” all work. Other items such as actor=<id> seem to work, but require you already know the id of the actor. TLDR: This is untested but seems to work. Use library section search when you can.

cleanBundles()[source]: Poster images and other metadata for items in your library are kept in “bundle” packages. When you remove items from your library, these bundles aren’t immediately removed. Removing these old bundles can reduce the size of your install. By default, your server will automatically clean up old bundles once a week as part of Scheduled Tasks.

emptyTrash()[source]: If a library has items in the Library Trash, use this option to empty the Trash.

optimize()[source]: The Optimize option cleans up the server database from unused or fragmented data. For example, if you have deleted or added an entire library or many items in a library, you may like to optimize the database.

update()[source]: Scan this library for new items.

cancelUpdate()[source]: Cancel a library update.

refresh()[source]: Forces a download of fresh media information from the internet. This can take a long time. Any locked fields are not modified.

deleteMediaPreviews()[source]: Delete the preview thumbnails for the all sections. This cannot be undone. Recreating media preview files can take hours or even days.

add(name='', type='', agent='', scanner='', location='', language='en', *args, **kwargs)[source]

Simplified add for the most common options.

Parameters:

name (str) – Name of the library
agent (str) – Example com.plexapp.agents.imdb
type (str) – movie, show, # check me
location (str or list) – /path/to/files, [“/path/to/files”, “/path/to/morefiles”]
language (str) – Two letter language fx en
kwargs (dict) – Advanced options should be passed as a dict. where the id is the key.

Photo Preferences

agent (str): com.plexapp.agents.none

enableAutoPhotoTags (bool): Tag photos. Default value false.

enableBIFGeneration (bool): Enable video preview thumbnails. Default value true.

includeInGlobal (bool): Include in dashboard. Default value true.

scanner (str): Plex Photo Scanner

Movie Preferences

agent (str): com.plexapp.agents.none, com.plexapp.agents.imdb, tv.plex.agents.movie, com.plexapp.agents.themoviedb

enableBIFGeneration (bool): Enable video preview thumbnails. Default value true.

enableCinemaTrailers (bool): Enable Cinema Trailers. Default value true.

includeInGlobal (bool): Include in dashboard. Default value true.

scanner (str): Plex Movie, Plex Movie Scanner, Plex Video Files Scanner, Plex Video Files

IMDB Movie Options (com.plexapp.agents.imdb)

title (bool): Localized titles. Default value false.

extras (bool): Find trailers and extras automatically (Plex Pass required). Default value true.

only_trailers (bool): Skip extras which aren’t trailers. Default value false.

redband (bool): Use red band (restricted audiences) trailers when available. Default value false.

native_subs (bool): Include extras with subtitles in Library language. Default value false.

cast_list (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.

ratings (int): Ratings Source, Default value 0 Possible options: 0:Rotten Tomatoes, 1:IMDb, 2:The Movie Database.

summary (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.

country (int): Default value 46 Possible options 0:Argentina, 1:Australia, 2:Austria, 3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica, 11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador, 16:France, 17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland, 22:Italy, 23:Jamaica, 24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands, 29:New Zealand, 30:Nicaragua, 31:Panama, 32:Paraguay, 33:Peru, 34:Portugal, 35:Peoples Republic of China, 36:Puerto Rico, 37:Russia, 38:Singapore, 39:South Africa, 40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad, 45:United Kingdom, 46:United States, 47:Uruguay, 48:Venezuela.

collections (bool): Use collection info from The Movie Database. Default value false.

localart (bool): Prefer artwork based on library language. Default value true.

adult (bool): Include adult content. Default value false.

usage (bool): Send anonymous usage data to Plex. Default value true.

TheMovieDB Movie Options (com.plexapp.agents.themoviedb)

collections (bool): Use collection info from The Movie Database. Default value false.

localart (bool): Prefer artwork based on library language. Default value true.

adult (bool): Include adult content. Default value false.

country (int): Country (used for release date and content rating). Default value 47 Possible options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada, 9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador, 16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland, 23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands, 30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal, 36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa, 41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.

Show Preferences

agent (str): com.plexapp.agents.none, com.plexapp.agents.thetvdb, com.plexapp.agents.themoviedb, tv.plex.agents.series

enableBIFGeneration (bool): Enable video preview thumbnails. Default value true.

episodeSort (int): Episode order. Default -1 Possible options: 0:Oldest first, 1:Newest first.

flattenSeasons (int): Seasons. Default value 0 Possible options: 0:Show,1:Hide.

includeInGlobal (bool): Include in dashboard. Default value true.

scanner (str): Plex TV Series, Plex Series Scanner

TheTVDB Show Options (com.plexapp.agents.thetvdb)

extras (bool): Find trailers and extras automatically (Plex Pass required). Default value true.

native_subs (bool): Include extras with subtitles in Library language. Default value false.

TheMovieDB Show Options (com.plexapp.agents.themoviedb)

collections (bool): Use collection info from The Movie Database. Default value false.

localart (bool): Prefer artwork based on library language. Default value true.

adult (bool): Include adult content. Default value false.

country (int): Country (used for release date and content rating). Default value 47 options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada, 9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador, 16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland, 23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands, 30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal, 36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa, 41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.

Other Video Preferences

agent (str): com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb

enableBIFGeneration (bool): Enable video preview thumbnails. Default value true.

enableCinemaTrailers (bool): Enable Cinema Trailers. Default value true.

includeInGlobal (bool): Include in dashboard. Default value true.

scanner (str): Plex Movie Scanner, Plex Video Files Scanner

IMDB Other Video Options (com.plexapp.agents.imdb)

title (bool): Localized titles. Default value false.

extras (bool): Find trailers and extras automatically (Plex Pass required). Default value true.

only_trailers (bool): Skip extras which aren’t trailers. Default value false.

redband (bool): Use red band (restricted audiences) trailers when available. Default value false.

native_subs (bool): Include extras with subtitles in Library language. Default value false.

cast_list (int): Cast List Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.

ratings (int): Ratings Source Default value 0 Possible options: 0:Rotten Tomatoes,1:IMDb,2:The Movie Database.

summary (int): Plot Summary Source: Default value 1 Possible options: 0:IMDb,1:The Movie Database.

country (int): Country: Default value 46 Possible options: 0:Argentina, 1:Australia, 2:Austria, 3:Belgium, 4:Belize, 5:Bolivia, 6:Brazil, 7:Canada, 8:Chile, 9:Colombia, 10:Costa Rica, 11:Czech Republic, 12:Denmark, 13:Dominican Republic, 14:Ecuador, 15:El Salvador, 16:France, 17:Germany, 18:Guatemala, 19:Honduras, 20:Hong Kong SAR, 21:Ireland, 22:Italy, 23:Jamaica, 24:Korea, 25:Liechtenstein, 26:Luxembourg, 27:Mexico, 28:Netherlands, 29:New Zealand, 30:Nicaragua, 31:Panama, 32:Paraguay, 33:Peru, 34:Portugal, 35:Peoples Republic of China, 36:Puerto Rico, 37:Russia, 38:Singapore, 39:South Africa, 40:Spain, 41:Sweden, 42:Switzerland, 43:Taiwan, 44:Trinidad, 45:United Kingdom, 46:United States, 47:Uruguay, 48:Venezuela.

collections (bool): Use collection info from The Movie Database. Default value false.

localart (bool): Prefer artwork based on library language. Default value true.

adult (bool): Include adult content. Default value false.

usage (bool): Send anonymous usage data to Plex. Default value true.

TheMovieDB Other Video Options (com.plexapp.agents.themoviedb)

collections (bool): Use collection info from The Movie Database. Default value false.

localart (bool): Prefer artwork based on library language. Default value true.

adult (bool): Include adult content. Default value false.

country (int): Country (used for release date and content rating). Default value 47 Possible options 0:, 1:Argentina, 2:Australia, 3:Austria, 4:Belgium, 5:Belize, 6:Bolivia, 7:Brazil, 8:Canada, 9:Chile, 10:Colombia, 11:Costa Rica, 12:Czech Republic, 13:Denmark, 14:Dominican Republic, 15:Ecuador, 16:El Salvador, 17:France, 18:Germany, 19:Guatemala, 20:Honduras, 21:Hong Kong SAR, 22:Ireland, 23:Italy, 24:Jamaica, 25:Korea, 26:Liechtenstein, 27:Luxembourg, 28:Mexico, 29:Netherlands, 30:New Zealand, 31:Nicaragua, 32:Panama, 33:Paraguay, 34:Peru, 35:Portugal, 36:Peoples Republic of China, 37:Puerto Rico, 38:Russia, 39:Singapore, 40:South Africa, 41:Spain, 42:Sweden, 43:Switzerland, 44:Taiwan, 45:Trinidad, 46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.

history(maxresults=None, mindate=None)[source]: Get Play History for all library Sections for the owner. :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime

tags(tag)[source]

Returns a list of LibraryMediaTag objects for the specified tag.

Parameters:: tag (str) – Tag name (see TAGTYPES).

class plexapi.library.LibrarySection(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Base class for a single library section.

Variables:

agent (str) – The metadata agent used for the library section (com.plexapp.agents.imdb, etc).
allowSync (bool) – True if you allow syncing content from the library section.
art (str) – Background artwork used to respresent the library section.
composite (str) – Composite image used to represent the library section.
createdAt (datetime) – Datetime the library section was created.
filters (bool) – True if filters are available for the library section.
key (int) – Key (or ID) of this library section.
language (str) – Language represented in this section (en, xn, etc).
locations (List<str>) – List of folder paths added to the library section.
refreshing (bool) – True if this section is currently being refreshed.
scanner (str) – Internal scanner used to find media (Plex Movie Scanner, Plex Premium Music Scanner, etc.)
thumb (str) – Thumbnail image used to represent the library section.
title (str) – Name of the library section.
type (str) – Type of content section represents (movie, show, artist, photo).
updatedAt (datetime) – Datetime the library section was last updated.
uuid (str) – Unique id for the section (32258d7c-3e6c-4ac5-98ad-bad7a3b78c63)

property totalSize: Returns the total number of items in the library for the default library type.

property totalDuration: Returns the total duration (in milliseconds) of items in the library.

property totalStorage: Returns the total storage (in bytes) of items in the library.

totalViewSize(libtype=None, includeCollections=True)[source]

Returns the total number of items in the library for a specified libtype. The number of items for the default library type will be returned if no libtype is specified. (e.g. Specify libtype='episode' for the total number of episodes or libtype='albums' for the total number of albums.)

Parameters:

libtype (str, optional) – The type of items to return the total number for (movie, show, season, episode, artist, album, track, photoalbum). Default is the main library type.
includeCollections (bool, optional) – True or False to include collections in the total number. Default is True.

delete()[source]: Delete a library section.

reload()[source]: Reload the data for the library section.

edit(agent=None, **kwargs)[source]

Edit a library. See Library for example usage.

Parameters:

agent (str, optional) – The library agent.
kwargs (dict) – Dict of settings to edit.

addLocations(location)[source]

Add a location to a library.

Parameters:: location (str or list) – A single folder path, list of paths.

Example

LibrarySection.addLocations('/path/1')
LibrarySection.addLocations(['/path/1', 'path/2', '/path/3'])

removeLocations(location)[source]

Remove a location from a library.

Parameters:: location (str or list) – A single folder path, list of paths.

Example

LibrarySection.removeLocations('/path/1')
LibrarySection.removeLocations(['/path/1', 'path/2', '/path/3'])

get(title, **kwargs)[source]

Returns the media item with the specified title and kwargs.

Parameters:

title (str) – Title of the item to return.
kwargs (dict) – Additional search parameters. See search() for more info.

Raises:

NotFound – The title is not found in the library.

getGuid(guid)[source]

Returns the media item with the specified external Plex, IMDB, TMDB, or TVDB ID. Note: Only available for the Plex Movie and Plex TV Series agents.

Parameters:: guid (str) – The external guid of the item to return. Examples: Plex plex://show/5d9c086c46115600200aa2fe IMDB imdb://tt0944947, TMDB tmdb://1399, TVDB tvdb://121361.
Raises:: NotFound – The guid is not found in the library.

Example

result1 = library.getGuid('plex://show/5d9c086c46115600200aa2fe')
result2 = library.getGuid('imdb://tt0944947')
result3 = library.getGuid('tmdb://1399')
result4 = library.getGuid('tvdb://121361')

# Alternatively, create your own guid lookup dictionary for faster performance
guidLookup = {}
for item in library.all():
    guidLookup[item.guid] = item
    guidLookup.update({guid.id: item for guid in item.guids})

result1 = guidLookup['plex://show/5d9c086c46115600200aa2fe']
result2 = guidLookup['imdb://tt0944947']
result3 = guidLookup['tmdb://1399']
result4 = guidLookup['tvdb://121361']

all(libtype=None, **kwargs)[source]: Returns a list of all items from this library section. See description of search() for details about filtering / sorting.

folders()[source]: Returns a list of available Folder for this library section.

managedHubs()[source]: Returns a list of available ManagedHub for this library section.

resetManagedHubs()[source]: Reset the managed hub customizations for this library section.

hubs()[source]: Returns a list of available Hub for this library section.

agents()[source]: Returns a list of available Agent for this library section.

settings()[source]: Returns a list of all library settings.

editAdvanced(**kwargs)[source]: Edit a library’s advanced settings.

defaultAdvanced()[source]: Edit all of library’s advanced settings to default.

lockAllField(field, libtype=None)[source]

Lock a field for all items in the library.

Parameters:

field (str) – The field to lock (e.g. thumb, rating, collection).
libtype (str, optional) – The library type to lock (movie, show, season, episode, artist, album, track, photoalbum, photo). Default is the main library type.

unlockAllField(field, libtype=None)[source]

Unlock a field for all items in the library.

Parameters:

field (str) – The field to unlock (e.g. thumb, rating, collection).
libtype (str, optional) – The library type to lock (movie, show, season, episode, artist, album, track, photoalbum, photo). Default is the main library type.

timeline()[source]: Returns a timeline query for this library section.

onDeck()[source]: Returns a list of media items on deck from this library section.

continueWatching()[source]: Return a list of media items in the library’s Continue Watching hub.

recentlyAdded(maxresults=50, libtype=None)[source]

Returns a list of media items recently added from this library section.

Parameters:

maxresults (int) – Max number of items to return (default 50).
libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo). Default is the main library type.

analyze()[source]: Run an analysis on all of the items in this library section. See See analyze() for more details.

emptyTrash()[source]: If a section has items in the Trash, use this option to empty the Trash.

update(path=None)[source]

Scan this section for new media.

Parameters:: path (str, optional) – Full path to folder to scan.

cancelUpdate()[source]: Cancel update of this Library Section.

refresh()[source]: Forces a download of fresh media information from the internet. This can take a long time. Any locked fields are not modified.

deleteMediaPreviews()[source]: Delete the preview thumbnails for items in this library. This cannot be undone. Recreating media preview files can take hours or even days.

filterTypes()[source]: Returns a list of available FilteringType for this library section.

getFilterType(libtype=None)[source]

Returns a FilteringType for a specified libtype.

Parameters:: libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).
Raises:: NotFound – Unknown libtype for this library.

fieldTypes()[source]: Returns a list of available FilteringFieldType for this library section.

getFieldType(fieldType)[source]

Returns a FilteringFieldType for a specified fieldType.

Parameters:: fieldType (str) – The data type for the field (tag, integer, string, boolean, date, subtitleLanguage, audioLanguage, resolution).
Raises:: NotFound – Unknown fieldType for this library.

listFilters(libtype=None)[source]

Returns a list of available FilteringFilter for a specified libtype. This is the list of options in the filter dropdown menu (screenshot).

Parameters:: libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

Example

availableFilters = [f.filter for f in library.listFilters()]
print("Available filter fields:", availableFilters)

listSorts(libtype=None)[source]

Returns a list of available FilteringSort for a specified libtype. This is the list of options in the sorting dropdown menu (screenshot).

Parameters:: libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

Example

availableSorts = [f.key for f in library.listSorts()]
print("Available sort fields:", availableSorts)

listFields(libtype=None)[source]

Returns a list of available FilteringFields for a specified libtype. This is the list of options in the custom filter dropdown menu (screenshot).

Parameters:: libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

Example

availableFields = [f.key.split('.')[-1] for f in library.listFields()]
print("Available fields:", availableFields)

listOperators(fieldType)[source]

Returns a list of available FilteringOperator for a specified fieldType. This is the list of options in the custom filter operator dropdown menu (screenshot).

Parameters:: fieldType (str) – The data type for the field (tag, integer, string, boolean, date, subtitleLanguage, audioLanguage, resolution).

Example

field = 'genre'  # Available filter field from listFields()
filterField = next(f for f in library.listFields() if f.key.endswith(field))
availableOperators = [o.key for o in library.listOperators(filterField.type)]
print(f"Available operators for {field}:", availableOperators)

listFilterChoices(field, libtype=None)[source]

Returns a list of available FilterChoice for a specified FilteringFilter or filter field. This is the list of available values for a custom filter (screenshot).

Parameters:

field (str) – FilteringFilter object, or the name of the field (genre, year, contentRating, etc.).
libtype (str, optional) – The library type to filter (movie, show, season, episode, artist, album, track, photoalbum, photo, collection).

Raises:

BadRequest – Invalid filter field.
NotFound – Unknown filter field.

Example

field = 'genre'  # Available filter field from listFilters()
availableChoices = [f.title for f in library.listFilterChoices(field)]
print(f"Available choices for {field}:", availableChoices)

hubSearch(query, mediatype=None, limit=None)[source]: Returns the hub search results for this library. See plexapi.server.PlexServer.search() for details and parameters.

search(title=None, sort=None, maxresults=None, libtype=None, container_start=None, container_size=None, limit=None, filters=None, **kwargs)[source]

Search the library. The http requests will be batched in container_size. If you are only looking for the first <num> results, it would be wise to set the maxresults option to that amount so the search doesn’t iterate over all results on the server.

Parameters:

title (str, optional) – General string query to search for. Partial string matches are allowed.
sort (FilteringSort or str or list, optional) – A field to sort the results. See the details below for more info.
maxresults (int, optional) – Only return the specified number of results.
libtype (str, optional) – Return results of a specific type (movie, show, season, episode, artist, album, track, photoalbum, photo, collection) (e.g. libtype='episode' will only return Episode objects)
container_start (int, optional) – Default 0.
container_size (int, optional) – Default X_PLEX_CONTAINER_SIZE in your config file.
limit (int, optional) – Limit the number of results from the filter.
filters (dict, optional) – A dictionary of advanced filters. See the details below for more info.
**kwargs (dict) – Additional custom filters to apply to the search results. See the details below for more info.

Raises:

BadRequest – When the sort or filter is invalid.
NotFound – When applying an unknown sort or filter.

Sorting Results

The search results can be sorted by including the sort parameter.

See listSorts() to get a list of available sort fields.

The sort parameter can be a FilteringSort object or a sort string in the format field:dir. The sort direction dir can be asc, desc, or nullsLast. Omitting the sort direction or using a FilteringSort object will sort the results in the default direction of the field. Multi-sorting on multiple fields can be achieved by using a comma separated list of sort strings, or a list of FilteringSort object or strings.

Examples

library.search(sort="titleSort:desc")  # Sort title in descending order
library.search(sort="titleSort")  # Sort title in the default order
# Multi-sort by year in descending order, then by audience rating in descending order
library.search(sort="year:desc,audienceRating:desc")
library.search(sort=["year:desc", "audienceRating:desc"])

Using Plex Filters

Any of the available custom filters can be applied to the search results (screenshot).

See listFields() to get a list of all available fields.
See listOperators() to get a list of all available operators.
See listFilterChoices() to get a list of all available filter values.

The following filter fields are just some examples of the possible filters. The list is not exhaustive, and not all filters apply to all library types.

actor (MediaTag): Search for the name of an actor.
addedAt (datetime): Search for items added before or after a date. See operators below.
audioLanguage (str): Search for a specific audio language (3 character code, e.g. jpn).
collection (MediaTag): Search for the name of a collection.
contentRating (MediaTag): Search for a specific content rating.
country (MediaTag): Search for the name of a country.
decade (int): Search for a specific decade (e.g. 2000).
director (MediaTag): Search for the name of a director.
duplicate (bool) Search for duplicate items.
genre (MediaTag): Search for a specific genre.
hdr (bool): Search for HDR items.
inProgress (bool): Search for in progress items.
label (MediaTag): Search for a specific label.
lastViewedAt (datetime): Search for items watched before or after a date. See operators below.
mood (MediaTag): Search for a specific mood.
producer (MediaTag): Search for the name of a producer.
resolution (str): Search for a specific resolution (e.g. 1080).
studio (str): Search for the name of a studio.
style (MediaTag): Search for a specific style.
subtitleLanguage (str): Search for a specific subtitle language (3 character code, e.g. eng)
unmatched (bool): Search for unmatched items.
unwatched (bool): Search for unwatched items.
userRating (int): Search for items with a specific user rating.
writer (MediaTag): Search for the name of a writer.
year (int): Search for a specific year.

Tag type filter values can be a FilterChoice object, MediaTag object, the exact name MediaTag.tag (str), or the exact id MediaTag.id (int).

Date type filter values can be a datetime object, a relative date using a one of the available date suffixes (e.g. 30d) (str), or a date in YYYY-MM-DD (str) format.

Relative date suffixes:

s: seconds
m: minutes
h: hours
d: days
w: weeks
mon: months
y: years

Multiple values can be OR together by providing a list of values.

Examples

library.search(unwatched=True, year=2020, resolution="4k")
library.search(actor="Arnold Schwarzenegger", decade=1990)
library.search(contentRating="TV-G", genre="animation")
library.search(genre=["animation", "comedy"])  # Genre is animation OR comedy
library.search(studio=["Disney", "Pixar"])  # Studio contains Disney OR Pixar

Using a libtype Prefix

Some filters may be prefixed by the libtype separated by a . (e.g. show.collection, episode.title, artist.style, album.genre, track.userRating, etc.). This should not be confused with the libtype parameter. If no libtype prefix is provided, then the default library type is assumed. For example, in a TV show library viewCount is assumed to be show.viewCount. If you want to filter using episode view count then you must specify episode.viewCount explicitly. In addition, if the filter does not exist for the default library type it will fallback to the most specific libtype available. For example, show.unwatched does not exists so it will fallback to episode.unwatched. The libtype prefix cannot be included directly in the function parameters so the filters must be provided as a filters dictionary.

Examples

library.search(filters={"show.collection": "Documentary", "episode.inProgress": True})
library.search(filters={"artist.genre": "pop", "album.decade": 2000})

# The following three options are identical and will return Episode objects
showLibrary.search(title="Winter is Coming", libtype='episode')
showLibrary.search(libtype='episode', filters={"episode.title": "Winter is Coming"})
showLibrary.searchEpisodes(title="Winter is Coming")

# The following will search for the episode title but return Show objects
showLibrary.search(filters={"episode.title": "Winter is Coming"})

# The following will fallback to episode.unwatched
showLibrary.search(unwatched=True)

Using Plex Operators

Operators can be appended to the filter field to narrow down results with more granularity. The following is a list of possible operators depending on the data type of the filter being applied. A special & operator can also be used to AND together a list of values.

Type: MediaTag or subtitleLanguage or audioLanguage

no operator: is
!: is not

Type: int

no operator: is
!: is not
>>: is greater than
<<: is less than

Type: str

no operator: contains
!: does not contain
=: is
!=: is not
<: begins with
>: ends with

Type: bool

no operator: is true
!: is false

Type: datetime

<<: is before
>>: is after

Type: resolution or guid

no operator: is

Operators cannot be included directly in the function parameters so the filters must be provided as a filters dictionary.

Examples

# Genre is horror AND thriller
library.search(filters={"genre&": ["horror", "thriller"]})

# Director is not Steven Spielberg
library.search(filters={"director!": "Steven Spielberg"})

# Title starts with Marvel and added before 2021-01-01
library.search(filters={"title<": "Marvel", "addedAt<<": "2021-01-01"})

# Added in the last 30 days using relative dates
library.search(filters={"addedAt>>": "30d"})

# Collection is James Bond and user rating is greater than 8
library.search(filters={"collection": "James Bond", "userRating>>": 8})

Using Advanced Filters

Any of the Plex filters described above can be combined into a single filters dictionary that mimics the advanced filters used in Plex Web with a tree of and/or branches. Each level of the tree must start with and (Match all of the following) or or (Match any of the following) as the dictionary key, and a list of dictionaries with the desired filters as the dictionary value.

The following example matches this advanced filter in Plex Web.

Examples

advancedFilters = {
    'and': [                            # Match all of the following in this list
        {
            'or': [                     # Match any of the following in this list
                {'title': 'elephant'},
                {'title': 'bunny'}
            ]
        },
        {'year>>': 1990},
        {'unwatched': True}
    ]
}
library.search(filters=advancedFilters)

Using PlexAPI Operators

For even more advanced filtering which cannot be achieved in Plex, the PlexAPI operators can be applied to any XML attribute. See plexapi.base.PlexObject.fetchItems() for a list of operators and how they are used. Note that using the Plex filters above will be faster since the filters are applied by the Plex server before the results are returned to PlexAPI. Using the PlexAPI operators requires the Plex server to return all results to allow PlexAPI to do the filtering. The Plex filters and the PlexAPI operators can be used in conjunction with each other.

Examples

library.search(summary__icontains="Christmas")
library.search(duration__gt=7200000)
library.search(audienceRating__lte=6.0, audienceRatingImage__startswith="rottentomatoes://")
library.search(media__videoCodec__exact="h265")
library.search(genre="holiday", viewCount__gte=3)

sync(policy, mediaSettings, client=None, clientId=None, title=None, sort=None, libtype=None, **kwargs)[source]

Add current library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for possible exceptions.

Parameters:

policy (Policy) – policy of syncing the media (how many items to sync and process watched media or not), generated automatically when method called on specific LibrarySection object.
mediaSettings (MediaSettings) – Transcoding settings used for the media, generated automatically when method called on specific LibrarySection object.
client (MyPlexDevice) – sync destination, see sync().
clientId (str) – sync destination, see sync().
title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current media.
sort (str) – formatted as column:dir; column can be any of {addedAt, originallyAvailableAt, lastViewedAt, titleSort, rating, mediaHeight, duration}. dir can be asc or desc.
libtype (str) – Filter results to a specific libtype (movie, show, episode, artist, album, track).

Returns:

an instance of created syncItem.

Return type:

Raises:

BadRequest – When the library is not allowed to sync.
BadRequest – When the sort or filter is invalid.
NotFound – When applying an unknown sort or filter.

Example

from plexapi import myplex
from plexapi.sync import Policy, MediaSettings, VIDEO_QUALITY_3_MBPS_720p

c = myplex.MyPlexAccount()
target = c.device('Plex Client')
sync_items_wd = c.syncItems(target.clientIdentifier)
srv = c.resource('Server Name').connect()
section = srv.library.section('Movies')
policy = Policy('count', unwatched=True, value=1)
media_settings = MediaSettings.create(VIDEO_QUALITY_3_MBPS_720p)
section.sync(target, policy, media_settings, title='Next best movie', sort='rating:desc')

history(maxresults=None, mindate=None)[source]: Get Play History for this library Section for the owner. :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime

createCollection(title, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs)[source]: Alias for createCollection() using this LibrarySection.

collection(title)[source]

Returns the collection with the specified title.

Parameters:: title (str) – Title of the item to return.
Raises:: NotFound – Unable to find collection.

collections(**kwargs)[source]: Returns a list of collections from this library section. See description of search() for details about filtering / sorting.

createPlaylist(title, items=None, smart=False, limit=None, sort=None, filters=None, m3ufilepath=None, **kwargs)[source]: Alias for createPlaylist() using this LibrarySection.

playlist(title)[source]

Returns the playlist with the specified title.

Parameters:: title (str) – Title of the item to return.
Raises:: NotFound – Unable to find playlist.

playlists(sort=None, **kwargs)[source]: Returns a list of playlists from this library section.

getWebURL(base=None, tab=None, key=None)[source]

Returns the Plex Web URL for the library.

Parameters:

base (str) – The base URL before the fragment (#!). Default is https://app.plex.tv/desktop.
tab (str) – The library tab (recommended, library, collections, playlists, timeline).
key (str) – A hub key.

common(items)[source]: Returns a Common object for the specified items.

multiEdit(items, **kwargs)[source]

Edit multiple objects at once. Note: This is a low level method and you need to know all the field/tag keys. See batchMultiEdits instead.

Parameters:

items (List) – List of Audio, Video, Photo, or Collection objects to be edited.
kwargs (dict) – Dict of settings to edit.

batchMultiEdits(items)[source]

Enable batch multi-editing mode to save API calls. Must call saveMultiEdits() at the end to save all the edits. See EditFieldMixin and EditTagsMixin for individual field and tag editing methods.

Parameters:: items (List) – List of Audio, Video, Photo, or Collection objects to be edited.

Example

movies = MovieSection.all()
items = [movies[0], movies[3], movies[5]]

# Batch multi-editing multiple fields and tags in a single API call
MovieSection.batchMultiEdits(items)
MovieSection.editTitle('A New Title').editSummary('A new summary').editTagline('A new tagline') \
    .addCollection('New Collection').removeGenre('Action').addLabel('Favorite')
MovieSection.saveMultiEdits()

saveMultiEdits()[source]: Save all the batch multi-edits. See batchMultiEdits() for details.

class plexapi.library.MovieSection(server, data, initpath=None, parent=None)[source]

Bases: LibrarySection, MovieEditMixins

Represents a LibrarySection section containing movies.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘movie’

searchMovies(**kwargs)[source]: Search for a movie. See search() for usage.

recentlyAddedMovies(maxresults=50)[source]

Returns a list of recently added movies from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

sync(videoQuality, limit=None, unwatched=False, **kwargs)[source]

Add current Movie library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for details on syncing libraries and possible exceptions.

Parameters:

videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module.
limit (int) – maximum count of movies to sync, unlimited if None.
unwatched (bool) – if True watched videos wouldn’t be synced.

Returns:

an instance of created syncItem.

Return type:

Example

from plexapi import myplex
from plexapi.sync import VIDEO_QUALITY_3_MBPS_720p

c = myplex.MyPlexAccount()
target = c.device('Plex Client')
sync_items_wd = c.syncItems(target.clientIdentifier)
srv = c.resource('Server Name').connect()
section = srv.library.section('Movies')
section.sync(VIDEO_QUALITY_3_MBPS_720p, client=target, limit=1, unwatched=True,
             title='Next best movie', sort='rating:desc')

class plexapi.library.ShowSection(server, data, initpath=None, parent=None)[source]

Bases: LibrarySection, ShowEditMixins, SeasonEditMixins, EpisodeEditMixins

Represents a LibrarySection section containing tv shows.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘show’

searchShows(**kwargs)[source]: Search for a show. See search() for usage.

searchSeasons(**kwargs)[source]: Search for a season. See search() for usage.

searchEpisodes(**kwargs)[source]: Search for an episode. See search() for usage.

recentlyAddedShows(maxresults=50)[source]

Returns a list of recently added shows from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

recentlyAddedSeasons(maxresults=50)[source]

Returns a list of recently added seasons from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

recentlyAddedEpisodes(maxresults=50)[source]

Returns a list of recently added episodes from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

sync(videoQuality, limit=None, unwatched=False, **kwargs)[source]

Add current Show library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for details on syncing libraries and possible exceptions.

Parameters:

videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module.
limit (int) – maximum count of episodes to sync, unlimited if None.
unwatched (bool) – if True watched videos wouldn’t be synced.

Returns:

an instance of created syncItem.

Return type:

Example

from plexapi import myplex
from plexapi.sync import VIDEO_QUALITY_3_MBPS_720p

c = myplex.MyPlexAccount()
target = c.device('Plex Client')
sync_items_wd = c.syncItems(target.clientIdentifier)
srv = c.resource('Server Name').connect()
section = srv.library.section('TV-Shows')
section.sync(VIDEO_QUALITY_3_MBPS_720p, client=target, limit=1, unwatched=True,
             title='Next unwatched episode')

class plexapi.library.MusicSection(server, data, initpath=None, parent=None)[source]

Bases: LibrarySection, ArtistEditMixins, AlbumEditMixins, TrackEditMixins

Represents a LibrarySection section containing music artists.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘artist’

albums()[source]: Returns a list of Album objects in this section.

stations()[source]: Returns a list of Playlist stations in this section.

searchArtists(**kwargs)[source]: Search for an artist. See search() for usage.

searchAlbums(**kwargs)[source]: Search for an album. See search() for usage.

searchTracks(**kwargs)[source]: Search for a track. See search() for usage.

recentlyAddedArtists(maxresults=50)[source]

Returns a list of recently added artists from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

recentlyAddedAlbums(maxresults=50)[source]

Returns a list of recently added albums from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

recentlyAddedTracks(maxresults=50)[source]

Returns a list of recently added tracks from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

sync(bitrate, limit=None, **kwargs)[source]

Add current Music library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for details on syncing libraries and possible exceptions.

Parameters:

bitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync.
limit (int) – maximum count of tracks to sync, unlimited if None.

Returns:

an instance of created syncItem.

Return type:

Example

from plexapi import myplex
from plexapi.sync import AUDIO_BITRATE_320_KBPS

c = myplex.MyPlexAccount()
target = c.device('Plex Client')
sync_items_wd = c.syncItems(target.clientIdentifier)
srv = c.resource('Server Name').connect()
section = srv.library.section('Music')
section.sync(AUDIO_BITRATE_320_KBPS, client=target, limit=100, sort='addedAt:desc',
             title='New music')

sonicAdventure(start: Track | int, end: Track | int, **kwargs: Any) → list[Track][source]

Returns a list of tracks from this library section that are part of a sonic adventure. ID’s should be of a track, other ID’s will return an empty list or items itself or an error.

Parameters:

start (Track | int) – The Track or ID of the first track in the sonic adventure.
end (Track | int) – The Track or ID of the last track in the sonic adventure.
kwargs – Additional parameters to pass to fetchItems().

Returns:

a list of tracks from this library section that are part of a sonic adventure.

Return type:

List[Track]

class plexapi.library.PhotoSection(server, data, initpath=None, parent=None)[source]

Bases: LibrarySection, PhotoalbumEditMixins, PhotoEditMixins

Represents a LibrarySection section containing photos.

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘photo’

all(libtype=None, **kwargs)[source]: Returns a list of all items from this library section. See description of plexapi.library.LibrarySection.search() for details about filtering / sorting.

collections(**kwargs)[source]: Returns a list of collections from this library section. See description of search() for details about filtering / sorting.

searchAlbums(**kwargs)[source]: Search for a photo album. See search() for usage.

searchPhotos(**kwargs)[source]: Search for a photo. See search() for usage.

recentlyAddedAlbums(maxresults=50)[source]

Returns a list of recently added photo albums from this library section.

Parameters:: maxresults (int) – Max number of items to return (default 50).

sync(resolution, limit=None, **kwargs)[source]

Add current Music library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for details on syncing libraries and possible exceptions.

Parameters:

resolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync.
limit (int) – maximum count of tracks to sync, unlimited if None.

Returns:

an instance of created syncItem.

Return type:

Example

from plexapi import myplex
from plexapi.sync import PHOTO_QUALITY_HIGH

c = myplex.MyPlexAccount()
target = c.device('Plex Client')
sync_items_wd = c.syncItems(target.clientIdentifier)
srv = c.resource('Server Name').connect()
section = srv.library.section('Photos')
section.sync(PHOTO_QUALITY_HIGH, client=target, limit=100, sort='addedAt:desc',
             title='Fresh photos')

class plexapi.library.LibraryTimeline(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a LibrarySection timeline.

Variables:

TAG (str) – ‘LibraryTimeline’
size (int) – Unknown
allowSync (bool) – Unknown
art (str) – Relative path to art image.
content (str) – “secondary”
identifier (str) – “com.plexapp.plugins.library”
latestEntryTime (int) – Epoch timestamp
mediaTagPrefix (str) – “/system/bundle/media/flags/”
mediaTagVersion (int) – Unknown
thumb (str) – Relative path to library thumb image.
title1 (str) – Name of library section.
updateQueueSize (int) – Number of items queued to update.
viewGroup (str) – “secondary”
viewMode (int) – Unknown

class plexapi.library.Location(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single library Location.

Variables:

TAG (str) – ‘Location’
id (int) – Location path ID.
path (str) – Path used for library..

class plexapi.library.Hub(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Hub (or category) in the PlexServer search.

Variables:

TAG (str) – ‘Hub’
context (str) – The context of the hub.
hubKey (str) – API URL for these specific hub items.
hubIdentifier (str) – The identifier of the hub.
items (list) – List of items in the hub.
key (str) – API URL for the hub.
more (bool) – True if there are more items to load (call reload() to fetch all items).
size (int) – The number of items in the hub.
style (str) – The style of the hub.
title (str) – The title of the hub.
type (str) – The type of items in the hub.

reload()[source]: Reloads the hub to fetch all items in the hub.

section()[source]: Returns the LibrarySection this hub belongs to.

class plexapi.library.LibraryMediaTag(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Base class of library media tags.

Variables:

TAG (str) – ‘Directory’
count (int) – The number of items where this tag is found.
filter (str) – The URL filter for the tag.
id (int) – The id of the tag.
key (str) – API URL (/library/section/<librarySectionID>/all?<filter>).
librarySectionID (int) – The library section ID where the tag is found.
librarySectionKey (str) – API URL for the library section (/library/section/<librarySectionID>)
librarySectionTitle (str) – The library title where the tag is found.
librarySectionType (int) – The library type where the tag is found.
reason (str) – The reason for the search result.
reasonID (int) – The reason ID for the search result.
reasonTitle (str) – The reason title for the search result.
score (float) – The score for the search result.
type (str) – The type of search result (tag).
tag (str) – The title of the tag.
tagKey (str) – The Plex Discover ratingKey (guid) for people.
tagType (int) – The type ID of the tag.
tagValue (int) – The value of the tag.
thumb (str) – The URL for the thumbnail of the tag (if available).

items(*args, **kwargs)[source]: Return the list of items within this tag.

class plexapi.library.Aperture(server, data, initpath=None, parent=None)[source]

Represents a single Aperture library media tag.

Variables:: TAGTYPE (int) – 202

class plexapi.library.Art(server, data, initpath=None, parent=None)[source]

Represents a single Art library media tag.

Variables:: TAGTYPE (int) – 313

class plexapi.library.Autotag(server, data, initpath=None, parent=None)[source]

Represents a single Autotag library media tag.

Variables:: TAGTYPE (int) – 207

class plexapi.library.Chapter(server, data, initpath=None, parent=None)[source]

Represents a single Chapter library media tag.

Variables:: TAGTYPE (int) – 9

class plexapi.library.Collection(server, data, initpath=None, parent=None)[source]

Represents a single Collection library media tag.

Variables:: TAGTYPE (int) – 2

class plexapi.library.Concert(server, data, initpath=None, parent=None)[source]

Represents a single Concert library media tag.

Variables:: TAGTYPE (int) – 306

class plexapi.library.Country(server, data, initpath=None, parent=None)[source]

Represents a single Country library media tag.

Variables:: TAGTYPE (int) – 8

class plexapi.library.Device(server, data, initpath=None, parent=None)[source]

Represents a single Device library media tag.

Variables:: TAGTYPE (int) – 206

class plexapi.library.Director(server, data, initpath=None, parent=None)[source]

Represents a single Director library media tag.

Variables:: TAGTYPE (int) – 4

class plexapi.library.Exposure(server, data, initpath=None, parent=None)[source]

Represents a single Exposure library media tag.

Variables:: TAGTYPE (int) – 203

class plexapi.library.Format(server, data, initpath=None, parent=None)[source]

Represents a single Format library media tag.

Variables:: TAGTYPE (int) – 302

class plexapi.library.Genre(server, data, initpath=None, parent=None)[source]

Represents a single Genre library media tag.

Variables:: TAGTYPE (int) – 1

class plexapi.library.Guid(server, data, initpath=None, parent=None)[source]

Represents a single Guid library media tag.

Variables:: TAGTYPE (int) – 314

class plexapi.library.ISO(server, data, initpath=None, parent=None)[source]

Represents a single ISO library media tag.

Variables:: TAGTYPE (int) – 204

class plexapi.library.Label(server, data, initpath=None, parent=None)[source]

Represents a single Label library media tag.

Variables:: TAGTYPE (int) – 11

class plexapi.library.Lens(server, data, initpath=None, parent=None)[source]

Represents a single Lens library media tag.

Variables:: TAGTYPE (int) – 205

class plexapi.library.Make(server, data, initpath=None, parent=None)[source]

Represents a single Make library media tag.

Variables:: TAGTYPE (int) – 200

class plexapi.library.Marker(server, data, initpath=None, parent=None)[source]

Represents a single Marker library media tag.

Variables:: TAGTYPE (int) – 12

class plexapi.library.MediaProcessingTarget(server, data, initpath=None, parent=None)[source]

Represents a single MediaProcessingTarget library media tag.

Variables:

TAG (str) – ‘Tag’
TAGTYPE (int) – 42

class plexapi.library.Model(server, data, initpath=None, parent=None)[source]

Represents a single Model library media tag.

Variables:: TAGTYPE (int) – 201

class plexapi.library.Mood(server, data, initpath=None, parent=None)[source]

Represents a single Mood library media tag.

Variables:: TAGTYPE (int) – 300

class plexapi.library.Network(server, data, initpath=None, parent=None)[source]

Represents a single Network library media tag.

Variables:: TAGTYPE (int) – 319

class plexapi.library.Place(server, data, initpath=None, parent=None)[source]

Represents a single Place library media tag.

Variables:: TAGTYPE (int) – 400

class plexapi.library.Poster(server, data, initpath=None, parent=None)[source]

Represents a single Poster library media tag.

Variables:: TAGTYPE (int) – 312

class plexapi.library.Producer(server, data, initpath=None, parent=None)[source]

Represents a single Producer library media tag.

Variables:: TAGTYPE (int) – 7

class plexapi.library.RatingImage(server, data, initpath=None, parent=None)[source]

Represents a single RatingImage library media tag.

Variables:: TAGTYPE (int) – 316

class plexapi.library.Review(server, data, initpath=None, parent=None)[source]

Represents a single Review library media tag.

Variables:: TAGTYPE (int) – 10

class plexapi.library.Role(server, data, initpath=None, parent=None)[source]

Represents a single Role library media tag.

Variables:: TAGTYPE (int) – 6

class plexapi.library.Similar(server, data, initpath=None, parent=None)[source]

Represents a single Similar library media tag.

Variables:: TAGTYPE (int) – 305

class plexapi.library.Studio(server, data, initpath=None, parent=None)[source]

Represents a single Studio library media tag.

Variables:: TAGTYPE (int) – 318

class plexapi.library.Style(server, data, initpath=None, parent=None)[source]

Represents a single Style library media tag.

Variables:: TAGTYPE (int) – 301

class plexapi.library.Tag(server, data, initpath=None, parent=None)[source]

Represents a single Tag library media tag.

Variables:: TAGTYPE (int) – 0

class plexapi.library.Theme(server, data, initpath=None, parent=None)[source]

Represents a single Theme library media tag.

Variables:: TAGTYPE (int) – 317

class plexapi.library.Writer(server, data, initpath=None, parent=None)[source]

Represents a single Writer library media tag.

Variables:: TAGTYPE (int) – 5

class plexapi.library.FilteringType(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single filtering Type object for a library.

Variables:

TAG (str) – ‘Type’
active (bool) – True if this filter type is currently active.
fields (List<FilteringField>) – List of field objects.
filters (List<FilteringFilter>) – List of filter objects.
key (str) – The API URL path for the libtype filter.
sorts (List<FilteringSort>) – List of sort objects.
title (str) – The title for the libtype filter.
type (str) – The libtype for the filter.

class plexapi.library.FilteringFilter(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Filter object for a FilteringType.

Variables:

TAG (str) – ‘Filter’
filter (str) – The key for the filter.
filterType (str) – The FilteringFieldType type (string, boolean, integer, date, etc).
key (str) – The API URL path for the filter.
title (str) – The title of the filter.
type (str) – ‘filter’

class plexapi.library.FilteringSort(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Sort object for a FilteringType.

Variables:

TAG (str) – ‘Sort’
active (bool) – True if the sort is currently active.
activeDirection (str) – The currently active sorting direction.
default (str) – The currently active default sorting direction.
defaultDirection (str) – The default sorting direction.
descKey (str) – The URL key for sorting with desc.
firstCharacterKey (str) – API URL path for first character endpoint.
key (str) – The URL key for the sorting.
title (str) – The title of the sorting.

class plexapi.library.FilteringField(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Field object for a FilteringType.

Variables:

TAG (str) – ‘Field’
key (str) – The URL key for the filter field.
title (str) – The title of the filter field.
type (str) – The FilteringFieldType type (string, boolean, integer, date, etc).
subType (str) – The subtype of the filter (decade, rating, etc).

class plexapi.library.FilteringFieldType(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single FieldType for library filtering.

Variables:

TAG (str) – ‘FieldType’
type (str) – The filtering data type (string, boolean, integer, date, etc).
operators (List<FilteringOperator>) – List of operator objects.

class plexapi.library.FilteringOperator(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents an single Operator for a FilteringFieldType.

Variables:

TAG (str) – ‘Operator’
key (str) – The URL key for the operator.
title (str) – The title of the operator.

class plexapi.library.FilterChoice(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single FilterChoice object. These objects are gathered when using filters while searching for library items and is the object returned in the result set of listFilterChoices().

Variables:

TAG (str) – ‘Directory’
fastKey (str) – API URL path to quickly list all items with this filter choice. (/library/sections/<section>/all?genre=<key>)
key (str) – The id value of this filter choice.
thumb (str) – Thumbnail URL for the filter choice.
title (str) – The title of the filter choice.
type (str) – The filter type (genre, contentRating, etc).

items()[source]: Returns a list of items for this filter choice.

class plexapi.library.ManagedHub(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Managed Hub (recommendation) inside a library.

Variables:

TAG (str) – ‘Hub’
deletable (bool) – True if the Hub can be deleted (promoted collection).
homeVisibility (str) – Promoted home visibility (none, all, admin, or shared).
identifier (str) – Hub identifier for the managed hub.
promotedToOwnHome (bool) – Promoted to own home.
promotedToRecommended (bool) – Promoted to recommended.
promotedToSharedHome (bool) – Promoted to shared home.
recommendationsVisibility (str) – Promoted recommendation visibility (none or all).
title (str) – Title of managed hub.

reload()[source]: Reload the data for this managed hub.

move(after=None)[source]

Move a managed hub to a new position in the library’s Managed Recommendations.

Parameters:: after (obj) – ManagedHub object to move the item after in the collection.
Raises:: plexapi.exceptions.BadRequest – When trying to move a Hub that is not a Managed Recommendation.

remove()[source]

Removes a managed hub from the library’s Managed Recommendations.

Raises:: plexapi.exceptions.BadRequest – When trying to remove a Hub that is not a Managed Recommendation or when the Hub cannot be removed.

updateVisibility(recommended=None, home=None, shared=None)[source]

Update the managed hub’s visibility settings.

Parameters:

recommended (bool) – True to make visible on your Library Recommended page. False to hide. Default None.
home (bool) – True to make visible on your Home page. False to hide. Default None.
shared (bool) – True to make visible on your Friends’ Home page. False to hide. Default None.

Example

managedHub.updateVisibility(recommended=True, home=True, shared=False).reload()
# or using chained methods
managedHub.promoteRecommended().promoteHome().demoteShared().reload()

promoteRecommended()[source]: Show the managed hub on your Library Recommended Page.

demoteRecommended()[source]: Hide the managed hub on your Library Recommended Page.

promoteHome()[source]: Show the managed hub on your Home Page.

demoteHome()[source]: Hide the manged hub on your Home Page.

promoteShared()[source]: Show the managed hub on your Friends’ Home Page.

demoteShared()[source]: Hide the managed hub on your Friends’ Home Page.

class plexapi.library.Folder(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Folder inside a library.

Variables:

key (str) – Url key for folder.
title (str) – Title of folder.

subfolders()[source]: Returns a list of available Folder for this folder. Continue down subfolders until a mediaType is found.

allSubfolders()[source]: Returns a list of all available Folder for this folder. Only returns Folder.

class plexapi.library.FirstCharacter(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a First Character element from a library.

Variables:

key (str) – Url key for character.
size (str) – Total amount of library items starting with this character.
title (str) – Character (#, !, A, B, C, …).

class plexapi.library.Path(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single directory Path.

Variables:

TAG (str) – ‘Path’
home (bool) – True if the path is the home directory
key (str) – API URL (/services/browse/<base64path>)
network (bool) – True if path is a network location
path (str) – Full path to folder
title (str) – Folder name

browse(includeFiles=True)[source]: Alias for browse().

walk()[source]: Alias for walk().

class plexapi.library.File(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single File.

Variables:

TAG (str) – ‘File’
key (str) – API URL (/services/browse/<base64path>)
path (str) – Full path to file
title (str) – File name

class plexapi.library.Common(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Common element from a library. This object lists common fields between multiple objects.

Variables:

TAG (str) – ‘Common’
collections (List<Collection>) – List of collection objects.
contentRating (str) – Content rating of the items.
countries (List<Country>) – List of countries objects.
directors (List<Director>) – List of director objects.
editionTitle (str) – Edition title of the items.
fields (List<Field>) – List of field objects.
genres (List<Genre>) – List of genre objects.
grandparentRatingKey (int) – Grandparent rating key of the items.
grandparentTitle (str) – Grandparent title of the items.
guid (str) – Plex GUID of the items.
guids (List<Guid>) – List of guid objects.
index (int) – Index of the items.
key (str) – API URL (/library/metadata/<ratingkey>).
labels (List<Label>) – List of label objects.
mixedFields (List<str>) – List of mixed fields.
moods (List<Mood>) – List of mood objects.
originallyAvailableAt (datetime) – Datetime of the release date of the items.
parentRatingKey (int) – Parent rating key of the items.
parentTitle (str) – Parent title of the items.
producers (List<Producer>) – List of producer objects.
ratingKey (int) – Rating key of the items.
ratings (List<Rating>) – List of rating objects.
roles (List<Role>) – List of role objects.
studio (str) – Studio name of the items.
styles (List<Style>) – List of style objects.
summary (str) – Summary of the items.
tagline (str) – Tagline of the items.
tags (List<Tag>) – List of tag objects.
title (str) – Title of the items.
titleSort (str) – Title to use when sorting of the items.
type (str) – Type of the media (common).
writers (List<Writer>) – List of writer objects.
year (int) – Year of the items.

property commonType: Returns the media type of the common items.

property ratingKeys: Returns a list of rating keys for the common items.

items()[source]: Returns a list of the common items.

Media plexapi.media

class plexapi.media.Media(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Container object for all MediaPart objects. Provides useful data about the video or audio this media belong to such as video framerate, resolution, etc.

Variables:

TAG (str) – ‘Media’
aspectRatio (float) – The aspect ratio of the media (ex: 2.35).
audioChannels (int) – The number of audio channels of the media (ex: 6).
audioCodec (str) – The audio codec of the media (ex: ac3).
audioProfile (str) – The audio profile of the media (ex: dts).
bitrate (int) – The bitrate of the media (ex: 1624).
container (str) – The container of the media (ex: avi).
duration (int) – The duration of the media in milliseconds (ex: 6990483).
height (int) – The height of the media in pixels (ex: 256).
id (int) – The unique ID for this media on the server.
has64bitOffsets (bool) – True if video has 64 bit offsets.
optimizedForStreaming (bool) – True if video is optimized for streaming.
parts (List<MediaPart>) – List of media part objects.
proxyType (int) – Equals 42 for optimized versions.
target (str) – The media version target name.
title (str) – The title of the media.
videoCodec (str) – The video codec of the media (ex: ac3).
videoFrameRate (str) – The video frame rate of the media (ex: 24p).
videoProfile (str) – The video profile of the media (ex: high).
videoResolution (str) – The video resolution of the media (ex: sd).
width (int) – The width of the video in pixels (ex: 608).
Photo_only_attributes –
The following attributes are only available for photos.
- aperture (str): The aperture used to take the photo.
- exposure (str): The exposure used to take the photo.
- iso (int): The iso used to take the photo.
- lens (str): The lens used to take the photo.
- make (str): The make of the camera used to take the photo.
- model (str): The model of the camera used to take the photo.

property isOptimizedVersion: Returns True if the media is a Plex optimized version.

class plexapi.media.MediaPart(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single media part (often a single file) for the media this belongs to.

Variables:

TAG (str) – ‘Part’
accessible (bool) – True if the file is accessible.
audioProfile (str) – The audio profile of the file.
container (str) – The container type of the file (ex: avi).
decision (str) – Unknown.
deepAnalysisVersion (int) – The Plex deep analysis version for the file.
duration (int) – The duration of the file in milliseconds.
exists (bool) – True if the file exists.
file (str) – The path to this file on disk (ex: /media/Movies/Cars (2006)/Cars (2006).mkv)
has64bitOffsets (bool) – True if the file has 64 bit offsets.
hasThumbnail (bool) – True if the file (track) has an embedded thumbnail.
id (int) – The unique ID for this media part on the server.
indexes (str, None) – sd if the file has generated preview (BIF) thumbnails.
key (str) – API URL (ex: /library/parts/46618/1389985872/file.mkv).
optimizedForStreaming (bool) – True if the file is optimized for streaming.
packetLength (int) – The packet length of the file.
requiredBandwidths (str) – The required bandwidths to stream the file.
selected (bool) – True if this media part is selected.
size (int) – The size of the file in bytes (ex: 733884416).
streams (List<MediaPartStream>) – List of stream objects.
syncItemId (int) – The unique ID for this media part if it is synced.
syncState (str) – The sync state for this media part.
videoProfile (str) – The video profile of the file.

property hasPreviewThumbnails: Returns True if the media part has generated preview (BIF) thumbnails.

videoStreams()[source]: Returns a list of VideoStream objects in this MediaPart.

audioStreams()[source]: Returns a list of AudioStream objects in this MediaPart.

subtitleStreams()[source]: Returns a list of SubtitleStream objects in this MediaPart.

lyricStreams()[source]: Returns a list of LyricStream objects in this MediaPart.

setSelectedAudioStream(stream)[source]

Set the selected AudioStream for this MediaPart.

Parameters:: stream (AudioStream) – Audio stream to set as selected

setSelectedSubtitleStream(stream)[source]

Set the selected SubtitleStream for this MediaPart.

Parameters:: stream (SubtitleStream) – Subtitle stream to set as selected.

resetSelectedSubtitleStream()[source]: Set the selected subtitle of this MediaPart to ‘None’.

class plexapi.media.MediaPartStream(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Base class for media streams. These consist of video, audio, subtitles, and lyrics.

Variables:

bitrate (int) – The bitrate of the stream.
codec (str) – The codec of the stream (ex: srt, ac3, mpeg4).
default (bool) – True if this is the default stream.
displayTitle (str) – The display title of the stream.
extendedDisplayTitle (str) – The extended display title of the stream.
key (str) – API URL (/library/streams/<id>)
id (int) – The unique ID for this stream on the server.
index (int) – The index of the stream.
language (str) – The language of the stream (ex: English, ไทย).
languageCode (str) – The ASCII language code of the stream (ex: eng, tha).
languageTag (str) – The two letter language tag of the stream (ex: en, fr).
requiredBandwidths (str) – The required bandwidths to stream the file.
selected (bool) – True if this stream is selected.
streamType (int) – The stream type (1= VideoStream, 2= AudioStream, 3= SubtitleStream).
title (str) – The title of the stream.
type (int) – Alias for streamType.

class plexapi.media.VideoStream(server, data, initpath=None, parent=None)[source]

Represents a video stream within a MediaPart.

Variables:

TAG (str) – ‘Stream’
STREAMTYPE (int) – 1
anamorphic (str) – If the video is anamorphic.
bitDepth (int) – The bit depth of the video stream (ex: 8).
cabac (int) – The context-adaptive binary arithmetic coding.
chromaLocation (str) – The chroma location of the video stream.
chromaSubsampling (str) – The chroma subsampling of the video stream (ex: 4:2:0).
codecID (str) – The codec ID (ex: XVID).
codedHeight (int) – The coded height of the video stream in pixels.
codedWidth (int) – The coded width of the video stream in pixels.
colorPrimaries (str) – The color primaries of the video stream.
colorRange (str) – The color range of the video stream.
colorSpace (str) – The color space of the video stream (ex: bt2020).
colorTrc (str) – The color trc of the video stream.
DOVIBLCompatID (int) – Dolby Vision base layer compatibility ID.
DOVIBLPresent (bool) – True if Dolby Vision base layer is present.
DOVIELPresent (bool) – True if Dolby Vision enhancement layer is present.
DOVILevel (int) – Dolby Vision level.
DOVIPresent (bool) – True if Dolby Vision is present.
DOVIProfile (int) – Dolby Vision profile.
DOVIRPUPresent (bool) – True if Dolby Vision reference processing unit is present.
DOVIVersion (float) – The Dolby Vision version.
duration (int) – The duration of video stream in milliseconds.
frameRate (float) – The frame rate of the video stream (ex: 23.976).
frameRateMode (str) – The frame rate mode of the video stream.
hasScalingMatrix (bool) – True if video stream has a scaling matrix.
height (int) – The height of the video stream in pixels (ex: 1080).
level (int) – The codec encoding level of the video stream (ex: 41).
profile (str) – The profile of the video stream (ex: asp).
pixelAspectRatio (str) – The pixel aspect ratio of the video stream.
pixelFormat (str) – The pixel format of the video stream.
refFrames (int) – The number of reference frames of the video stream.
scanType (str) – The scan type of the video stream (ex: progressive).
streamIdentifier (int) – The stream identifier of the video stream.
width (int) – The width of the video stream in pixels (ex: 1920).

class plexapi.media.AudioStream(server, data, initpath=None, parent=None)[source]

Represents a audio stream within a MediaPart.

Variables:

TAG (str) – ‘Stream’
STREAMTYPE (int) – 2
audioChannelLayout (str) – The audio channel layout of the audio stream (ex: 5.1(side)).
bitDepth (int) – The bit depth of the audio stream (ex: 16).
bitrateMode (str) – The bitrate mode of the audio stream (ex: cbr).
channels (int) – The number of audio channels of the audio stream (ex: 6).
duration (int) – The duration of audio stream in milliseconds.
profile (str) – The profile of the audio stream.
samplingRate (int) – The sampling rate of the audio stream (ex: xxx)
streamIdentifier (int) – The stream identifier of the audio stream.
Track_only_attributes –
The following attributes are only available for tracks.
- albumGain (float): The gain for the album.
- albumPeak (float): The peak for the album.
- albumRange (float): The range for the album.
- endRamp (str): The end ramp for the track.
- gain (float): The gain for the track.
- loudness (float): The loudness for the track.
- lra (float): The lra for the track.
- peak (float): The peak for the track.
- startRamp (str): The start ramp for the track.

setSelected()[source]: Sets this audio stream as the selected audio stream. Alias for setSelectedAudioStream().

class plexapi.media.SubtitleStream(server, data, initpath=None, parent=None)[source]

Represents a audio stream within a MediaPart.

Variables:

TAG (str) – ‘Stream’
STREAMTYPE (int) – 3
container (str) – The container of the subtitle stream.
forced (bool) – True if this is a forced subtitle.
format (str) – The format of the subtitle stream (ex: srt).
headerCompression (str) – The header compression of the subtitle stream.
hearingImpaired (bool) – True if this is a hearing impaired (SDH) subtitle.
perfectMatch (bool) – True if the on-demand subtitle is a perfect match.
providerTitle (str) – The provider title where the on-demand subtitle is downloaded from.
score (int) – The match score (download count) of the on-demand subtitle.
sourceKey (str) – The source key of the on-demand subtitle.
transient (str) – Unknown.
userID (int) – The user id of the user that downloaded the on-demand subtitle.

setSelected()[source]: Sets this subtitle stream as the selected subtitle stream. Alias for setSelectedSubtitleStream().

class plexapi.media.LyricStream(server, data, initpath=None, parent=None)[source]

Represents a lyric stream within a MediaPart.

Variables:

TAG (str) – ‘Stream’
STREAMTYPE (int) – 4
format (str) – The format of the lyric stream (ex: lrc).
minLines (int) – The minimum number of lines in the (timed) lyric stream.
provider (str) – The provider of the lyric stream (ex: com.plexapp.agents.lyricfind).
timed (bool) – True if the lyrics are timed to the track.

class plexapi.media.Session(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a current session.

Variables:

TAG (str) – ‘Session’
id (str) – The unique identifier for the session.
bandwidth (int) – The Plex streaming brain reserved bandwidth for the session.
location (str) – The location of the session (lan, wan, or cellular)

class plexapi.media.TranscodeSession(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a current transcode session.

Variables:

TAG (str) – ‘TranscodeSession’
audioChannels (int) – The number of audio channels of the transcoded media.
audioCodec (str) – The audio codec of the transcoded media.
audioDecision (str) – The transcode decision for the audio stream.
complete (bool) – True if the transcode is complete.
container (str) – The container of the transcoded media.
context (str) – The context for the transcode session.
duration (int) – The duration of the transcoded media in milliseconds.
height (int) – The height of the transcoded media in pixels.
key (str) – API URL (ex: /transcode/sessions/<id>).
maxOffsetAvailable (float) – Unknown.
minOffsetAvailable (float) – Unknown.
progress (float) – The progress percentage of the transcode.
protocol (str) – The protocol of the transcode.
remaining (int) – Unknown.
size (int) – The size of the transcoded media in bytes.
sourceAudioCodec (str) – The audio codec of the source media.
sourceVideoCodec (str) – The video codec of the source media.
speed (float) – The speed of the transcode.
subtitleDecision (str) – The transcode decision for the subtitle stream
throttled (bool) – True if the transcode is throttled.
timestamp (int) – The epoch timestamp when the transcode started.
transcodeHwDecoding (str) – The hardware transcoding decoder engine.
transcodeHwDecodingTitle (str) – The title of the hardware transcoding decoder engine.
transcodeHwEncoding (str) – The hardware transcoding encoder engine.
transcodeHwEncodingTitle (str) – The title of the hardware transcoding encoder engine.
transcodeHwFullPipeline (str) – True if hardware decoding and encoding is being used for the transcode.
transcodeHwRequested (str) – True if hardware transcoding was requested for the transcode.
videoCodec (str) – The video codec of the transcoded media.
videoDecision (str) – The transcode decision for the video stream.
width (str) – The width of the transcoded media in pixels.

class plexapi.media.TranscodeJob(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents an Optimizing job. TrancodeJobs are the process for optimizing conversions. Active or paused optimization items. Usually one item as a time.

class plexapi.media.Optimized(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Optimized item. Optimized items are optimized and queued conversions items.

items()[source]: Returns a list of all Video objects in this optimized item.

remove()[source]: Remove an Optimized item

rename(title)[source]: Rename an Optimized item

reprocess(ratingKey)[source]: Reprocess a removed Conversion item that is still a listed Optimize item

class plexapi.media.Conversion(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Conversion item. Conversions are items queued for optimization or being actively optimized.

remove()[source]: Remove Conversion from queue

move(after)[source]

Move Conversion items position in queue after (int): Place item after specified playQueueItemID. ‘-1’ is the active conversion.

Example:

Move 5th conversion Item to active conversion
conversions[4].move(‘-1’)

Move 4th conversion Item to 3rd in conversion queue
conversions[3].move(conversions[1].playQueueItemID)

class plexapi.media.MediaTag(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Base class for media tags used for filtering and searching your library items or navigating the metadata of media items in your library. Tags are the construct used for things such as Country, Director, Genre, etc.

Variables:

filter (str) – The library filter for the tag.
id (id) – Tag ID (This seems meaningless except to use it as a unique id).
key (str) – API URL (/library/section/<librarySectionID>/all?<filter>).
role (str) – The name of the character role for Role only.
tag (str) – Name of the tag. This will be Animation, SciFi etc for Genres. The name of person for Directors and Roles (ex: Animation, Stephen Graham, etc).
tagKey (str) – Plex GUID for the actor/actress for Role only.
thumb (str) – URL to thumbnail image for Role only.

items()[source]: Return the list of items within this tag.

class plexapi.media.Collection(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Collection media tag.

Variables:

TAG (str) – ‘Collection’
FILTER (str) – ‘collection’

collection()[source]: Return the Collection object for this collection tag.

class plexapi.media.Country(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Country media tag.

Variables:

TAG (str) – ‘Country’
FILTER (str) – ‘country’

class plexapi.media.Director(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Director media tag.

Variables:

TAG (str) – ‘Director’
FILTER (str) – ‘director’

class plexapi.media.Format(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Format media tag.

Variables:

TAG (str) – ‘Format’
FILTER (str) – ‘format’

class plexapi.media.Genre(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Genre media tag.

Variables:

TAG (str) – ‘Genre’
FILTER (str) – ‘genre’

class plexapi.media.Label(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Label media tag.

Variables:

TAG (str) – ‘Label’
FILTER (str) – ‘label’

class plexapi.media.Mood(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Mood media tag.

Variables:

TAG (str) – ‘Mood’
FILTER (str) – ‘mood’

class plexapi.media.Producer(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Producer media tag.

Variables:

TAG (str) – ‘Producer’
FILTER (str) – ‘producer’

class plexapi.media.Role(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Role (actor/actress) media tag.

Variables:

TAG (str) – ‘Role’
FILTER (str) – ‘role’

class plexapi.media.Similar(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Similar media tag.

Variables:

TAG (str) – ‘Similar’
FILTER (str) – ‘similar’

class plexapi.media.Style(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Style media tag.

Variables:

TAG (str) – ‘Style’
FILTER (str) – ‘style’

class plexapi.media.Subformat(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Subformat media tag.

Variables:

TAG (str) – ‘Subformat’
FILTER (str) – ‘subformat’

class plexapi.media.Tag(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Tag media tag.

Variables:

TAG (str) – ‘Tag’
FILTER (str) – ‘tag’

class plexapi.media.Writer(server, data, initpath=None, parent=None)[source]

Bases: MediaTag

Represents a single Writer media tag.

Variables:

TAG (str) – ‘Writer’
FILTER (str) – ‘writer’

class plexapi.media.Guid(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Guid media tag.

Variables:

TAG (str) – ‘Guid’
id (id) – The guid for external metadata sources (e.g. IMDB, TMDB, TVDB, MBID).

class plexapi.media.Rating(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Rating media tag.

Variables:

TAG (str) – ‘Rating’
image (str) – The uri for the rating image (e.g. imdb://image.rating, rottentomatoes://image.rating.ripe, rottentomatoes://image.rating.upright, themoviedb://image.rating).
type (str) – The type of rating (e.g. audience or critic).
value (float) – The rating value.

class plexapi.media.Review(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Review for a Movie.

Variables:

TAG (str) – ‘Review’
filter (str) – The library filter for the review.
id (int) – The ID of the review.
image (str) – The image uri for the review.
link (str) – The url to the online review.
source (str) – The source of the review.
tag (str) – The name of the reviewer.
text (str) – The text of the review.

class plexapi.media.BaseResource(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Base class for all Art, Poster, and Theme objects.

Variables:

TAG (str) – ‘Photo’ or ‘Track’
key (str) – API URL (/library/metadata/<ratingkey>).
provider (str) – The source of the resource. ‘local’ for local files (e.g. theme.mp3), None if uploaded or agent-/plugin-supplied.
ratingKey (str) – Unique key identifying the resource.
selected (bool) – True if the resource is currently selected.
thumb (str) – The URL to retrieve the resource thumbnail.

property resourceFilepath: Returns the file path to the resource in the Plex Media Server data directory. Note: Returns the URL if the resource is not stored locally.

class plexapi.media.Art(server, data, initpath=None, parent=None)[source]

Bases: BaseResource

Represents a single Art object.

class plexapi.media.Poster(server, data, initpath=None, parent=None)[source]

Bases: BaseResource

Represents a single Poster object.

class plexapi.media.Theme(server, data, initpath=None, parent=None)[source]

Bases: BaseResource

Represents a single Theme object.

class plexapi.media.Chapter(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Chapter media tag.

Variables:

TAG (str) – ‘Chapter’
end (int) – The end time of the chapter in milliseconds.
filter (str) – The library filter for the chapter.
id (int) – The ID of the chapter.
index (int) – The index of the chapter.
tag (str) – The name of the chapter.
title (str) – The title of the chapter.
thumb (str) – The URL to retrieve the chapter thumbnail.
start (int) – The start time of the chapter in milliseconds.

class plexapi.media.Marker(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Marker media tag.

Variables:

TAG (str) – ‘Marker’
end (int) – The end time of the marker in milliseconds.
final (bool) – True if the marker is the final credits marker.
id (int) – The ID of the marker.
type (str) – The type of marker.
start (int) – The start time of the marker in milliseconds.
version (int) – The Plex marker version.

property first: Returns True if the marker in the first credits marker.

class plexapi.media.Field(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Field.

Variables:

TAG (str) – ‘Field’
locked (bool) – True if the field is locked.
name (str) – The name of the field.

class plexapi.media.SearchResult(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single SearchResult.

Variables:: TAG (str) – ‘SearchResult’

class plexapi.media.Agent(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Agent.

Variables:: TAG (str) – ‘Agent’

class plexapi.media.AgentMediaType(server, data, initpath=None, parent=None)[source]

Bases: Agent

Represents a single Agent MediaType.

Variables:: TAG (str) – ‘MediaType’

class plexapi.media.Availability(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single online streaming service Availability.

Variables:

TAG (str) – ‘Availability’
country (str) – The streaming service country.
offerType (str) – Subscription, buy, or rent from the streaming service.
platform (str) – The platform slug for the streaming service.
platformColorThumb (str) – Thumbnail icon for the streaming service.
platformInfo (str) – The streaming service platform info.
platformUrl (str) – The URL to the media on the streaming service.
price (float) – The price to buy or rent from the streaming service.
priceDescription (str) – The display price to buy or rent from the streaming service.
quality (str) – The video quality on the streaming service.
title (str) – The title of the streaming service.
url (str) – The Plex availability URL.

Mixins plexapi.mixins

class plexapi.mixins.AdvancedSettingsMixin[source]

Bases: object

Mixin for Plex objects that can have advanced settings.

preferences()[source]: Returns a list of Preferences objects.

preference(pref)[source]

Returns a Preferences object for the specified pref.

Parameters:: pref (str) – The id of the preference to return.

editAdvanced(**kwargs)[source]: Edit a Plex object’s advanced settings.

defaultAdvanced()[source]: Edit all of a Plex object’s advanced settings to default.

class plexapi.mixins.SmartFilterMixin[source]

Bases: object

Mixin for Plex objects that can have smart filters.

class plexapi.mixins.SplitMergeMixin[source]

Bases: object

Mixin for Plex objects that can be split and merged.

split()[source]: Split duplicated Plex object into separate objects.

merge(ratingKeys)[source]

Merge other Plex objects into the current object.

Parameters:: ratingKeys (list) – A list of rating keys to merge.

class plexapi.mixins.UnmatchMatchMixin[source]

Bases: object

Mixin for Plex objects that can be unmatched and matched.

unmatch()[source]: Unmatches metadata match from object.

matches(agent=None, title=None, year=None, language=None)[source]

Return list of (SearchResult) metadata matches.

Parameters:
agent (str): Agent name to be used (imdb, thetvdb, themoviedb, etc.) title (str): Title of item to search for year (str): Year of item to search in language (str) : Language of item to search in

Examples

video.matches()
video.matches(title=”something”, year=2020)
video.matches(title=”something”)
video.matches(year=2020)
video.matches(title=”something”, year=””)
video.matches(title=””, year=2020)
video.matches(title=””, year=””)

The default behaviour in Plex Web = no params in plexapi
Both title and year specified by user
Year automatically filled in
Title automatically filled in
Explicitly searches for title with blank year
Explicitly searches for blank title with year
I don’t know what the user is thinking… return the same result as 1

For 2 to 7, the agent and language is automatically filled in

fixMatch(searchResult=None, auto=False, agent=None)[source]

Use match result to update show metadata.

Parameters:

auto (bool) – True uses first match from matches False allows user to provide the match
searchResult (SearchResult) – Search result from ~plexapi.base.matches()
agent (str) – Agent name to be used (imdb, thetvdb, themoviedb, etc.)

class plexapi.mixins.ExtrasMixin[source]

Bases: object

Mixin for Plex objects that can have extras.

extras()[source]: Returns a list of Extra objects.

class plexapi.mixins.HubsMixin[source]

Bases: object

Mixin for Plex objects that can have related hubs.

hubs()[source]: Returns a list of Hub objects.

class plexapi.mixins.PlayedUnplayedMixin[source]

Bases: object

Mixin for Plex objects that can be marked played and unplayed.

property isPlayed: Returns True if this video is played.

markPlayed()[source]: Mark the Plex object as played.

markUnplayed()[source]: Mark the Plex object as unplayed.

property isWatched: Alias to self.isPlayed.

markWatched()[source]: Alias to markPlayed().

markUnwatched()[source]: Alias to markUnplayed().

class plexapi.mixins.RatingMixin[source]

Bases: object

Mixin for Plex objects that can have user star ratings.

rate(rating=None)[source]

Rate the Plex object. Note: Plex ratings are displayed out of 5 stars (e.g. rating 7.0 = 3.5 stars).

Parameters:: rating (float, optional) – Rating from 0 to 10. Exclude to reset the rating.
Raises:: BadRequest – If the rating is invalid.

class plexapi.mixins.ArtUrlMixin[source]

Bases: object

Mixin for Plex objects that can have a background artwork url.

property artUrl: Return the art url for the Plex object.

class plexapi.mixins.ArtLockMixin[source]

Bases: object

Mixin for Plex objects that can have a locked background artwork.

lockArt()[source]: Lock the background artwork for a Plex object.

unlockArt()[source]: Unlock the background artwork for a Plex object.

class plexapi.mixins.ArtMixin[source]

Bases: ArtUrlMixin, ArtLockMixin

Mixin for Plex objects that can have background artwork.

arts()[source]: Returns list of available Art objects.

uploadArt(url=None, filepath=None)[source]

Upload a background artwork from a url or filepath.

Parameters:

url (str) – The full URL to the image to upload.
filepath (str) – The full file path the the image to upload or file-like object.

setArt(art)[source]

Set the background artwork for a Plex object.

Parameters:: art (Art) – The art object to select.

class plexapi.mixins.PosterUrlMixin[source]

Bases: object

Mixin for Plex objects that can have a poster url.

property thumbUrl: Return the thumb url for the Plex object.

property posterUrl: Alias to self.thumbUrl.

class plexapi.mixins.PosterLockMixin[source]

Bases: object

Mixin for Plex objects that can have a locked poster.

lockPoster()[source]: Lock the poster for a Plex object.

unlockPoster()[source]: Unlock the poster for a Plex object.

class plexapi.mixins.PosterMixin[source]

Bases: PosterUrlMixin, PosterLockMixin

Mixin for Plex objects that can have posters.

posters()[source]: Returns list of available Poster objects.

uploadPoster(url=None, filepath=None)[source]

Upload a poster from a url or filepath.

Parameters:

url (str) – The full URL to the image to upload.
filepath (str) – The full file path the the image to upload or file-like object.

setPoster(poster)[source]

Set the poster for a Plex object.

Parameters:: poster (Poster) – The poster object to select.

class plexapi.mixins.ThemeUrlMixin[source]

Bases: object

Mixin for Plex objects that can have a theme url.

property themeUrl: Return the theme url for the Plex object.

class plexapi.mixins.ThemeLockMixin[source]

Bases: object

Mixin for Plex objects that can have a locked theme.

lockTheme()[source]: Lock the theme for a Plex object.

unlockTheme()[source]: Unlock the theme for a Plex object.

class plexapi.mixins.ThemeMixin[source]

Bases: ThemeUrlMixin, ThemeLockMixin

Mixin for Plex objects that can have themes.

themes()[source]: Returns list of available Theme objects.

uploadTheme(url=None, filepath=None, timeout=None)[source]

Upload a theme from url or filepath.

Warning: Themes cannot be deleted using PlexAPI!

Parameters:

url (str) – The full URL to the theme to upload.
filepath (str) – The full file path to the theme to upload or file-like object.
timeout (int, optional) – Timeout, in seconds, to use when uploading themes to the server. (default config.TIMEOUT).

class plexapi.mixins.EditFieldMixin[source]

Bases: object

Mixin for editing Plex object fields.

editField(field, value, locked=True, **kwargs)[source]

Edit the field of a Plex object. All field editing methods can be chained together. Also see batchEdits() for batch editing fields.

Parameters:

field (str) – The name of the field to edit.
value (str) – The value to edit the field to.
locked (bool) – True (default) to lock the field, False to unlock the field.

Example

# Chaining multiple field edits with reloading
Movie.editTitle('A New Title').editSummary('A new summary').editTagline('A new tagline').reload()

class plexapi.mixins.AddedAtMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have an added at date.

editAddedAt(addedAt, locked=True)[source]

Edit the added at date.

Parameters:

addedAt (int or str or datetime) – The new value as a unix timestamp (int), “YYYY-MM-DD” (str), or datetime object.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.ContentRatingMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a content rating.

editContentRating(contentRating, locked=True)[source]

Edit the content rating.

Parameters:

contentRating (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.EditionTitleMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have an edition title.

editEditionTitle(editionTitle, locked=True)[source]

Edit the edition title. Plex Pass is required to edit this field.

Parameters:

editionTitle (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.OriginallyAvailableMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have an originally available date.

editOriginallyAvailable(originallyAvailable, locked=True)[source]

Edit the originally available date.

Parameters:

originallyAvailable (str or datetime) – The new value “YYYY-MM-DD (str) or datetime object.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.OriginalTitleMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have an original title.

editOriginalTitle(originalTitle, locked=True)[source]

Edit the original title.

Parameters:

originalTitle (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.SortTitleMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a sort title.

editSortTitle(sortTitle, locked=True)[source]

Edit the sort title.

Parameters:

sortTitle (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.StudioMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a studio.

editStudio(studio, locked=True)[source]

Edit the studio.

Parameters:

studio (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.SummaryMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a summary.

editSummary(summary, locked=True)[source]

Edit the summary.

Parameters:

summary (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TaglineMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a tagline.

editTagline(tagline, locked=True)[source]

Edit the tagline.

Parameters:

tagline (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TitleMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a title.

editTitle(title, locked=True)[source]

Edit the title.

Parameters:

title (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TrackArtistMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a track artist.

editTrackArtist(trackArtist, locked=True)[source]

Edit the track artist.

Parameters:

trackArtist (str) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TrackNumberMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a track number.

editTrackNumber(trackNumber, locked=True)[source]

Edit the track number.

Parameters:

trackNumber (int) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TrackDiscNumberMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a track disc number.

editDiscNumber(discNumber, locked=True)[source]

Edit the track disc number.

Parameters:

discNumber (int) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.PhotoCapturedTimeMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a captured time.

editCapturedTime(capturedTime, locked=True)[source]

Edit the photo captured time.

Parameters:

capturedTime (str or datetime) – The new value “YYYY-MM-DD hh:mm:ss” (str) or datetime object.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.UserRatingMixin[source]

Bases: EditFieldMixin

Mixin for Plex objects that can have a user rating.

editUserRating(userRating, locked=True)[source]

Edit the user rating.

Parameters:

userRating (int) – The new value.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.EditTagsMixin[source]

Bases: object

Mixin for editing Plex object tags.

editTags(tag, items, locked=True, remove=False, **kwargs)[source]

Edit the tags of a Plex object. All tag editing methods can be chained together. Also see batchEdits() for batch editing tags.

Parameters:

tag (str) – Name of the tag to edit.
items (List<str> or List<MediaTag>) – List of tags to add or remove.
locked (bool) – True (default) to lock the tags, False to unlock the tags.
remove (bool) – True to remove the tags in items.

Example

# Chaining multiple tag edits with reloading
Show.addCollection('New Collection').removeGenre('Action').addLabel('Favorite').reload()

class plexapi.mixins.CollectionMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have collections.

addCollection(collections, locked=True)[source]

Add a collection tag(s).

Parameters:

collections (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeCollection(collections, locked=True)[source]

Remove a collection tag(s).

Parameters:

collections (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.CountryMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have countries.

addCountry(countries, locked=True)[source]

Add a country tag(s).

Parameters:

countries (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeCountry(countries, locked=True)[source]

Remove a country tag(s).

Parameters:

countries (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.DirectorMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have directors.

addDirector(directors, locked=True)[source]

Add a director tag(s).

Parameters:

directors (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeDirector(directors, locked=True)[source]

Remove a director tag(s).

Parameters:

directors (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.GenreMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have genres.

addGenre(genres, locked=True)[source]

Add a genre tag(s).

Parameters:

genres (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeGenre(genres, locked=True)[source]

Remove a genre tag(s).

Parameters:

genres (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.LabelMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have labels.

addLabel(labels, locked=True)[source]

Add a label tag(s).

Parameters:

labels (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeLabel(labels, locked=True)[source]

Remove a label tag(s).

Parameters:

labels (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.MoodMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have moods.

addMood(moods, locked=True)[source]

Add a mood tag(s).

Parameters:

moods (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeMood(moods, locked=True)[source]

Remove a mood tag(s).

Parameters:

moods (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.ProducerMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have producers.

addProducer(producers, locked=True)[source]

Add a producer tag(s).

Parameters:

producers (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeProducer(producers, locked=True)[source]

Remove a producer tag(s).

Parameters:

producers (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.SimilarArtistMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have similar artists.

addSimilarArtist(artists, locked=True)[source]

Add a similar artist tag(s).

Parameters:

artists (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeSimilarArtist(artists, locked=True)[source]

Remove a similar artist tag(s).

Parameters:

artists (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.StyleMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have styles.

addStyle(styles, locked=True)[source]

Add a style tag(s).

Parameters:

styles (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeStyle(styles, locked=True)[source]

Remove a style tag(s).

Parameters:

styles (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.TagMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have tags.

addTag(tags, locked=True)[source]

Add a tag(s).

Parameters:

tags (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeTag(tags, locked=True)[source]

Remove a tag(s).

Parameters:

tags (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.WriterMixin[source]

Bases: EditTagsMixin

Mixin for Plex objects that can have writers.

addWriter(writers, locked=True)[source]

Add a writer tag(s).

Parameters:

writers (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

removeWriter(writers, locked=True)[source]

Remove a writer tag(s).

Parameters:

writers (List<str> or List<MediaTag>) – List of tags.
locked (bool) – True (default) to lock the field, False to unlock the field.

class plexapi.mixins.WatchlistMixin[source]

Bases: object

Mixin for Plex objects that can be added to a user’s watchlist.

onWatchlist(account=None)[source]

Returns True if the item is on the user’s watchlist. Also see onWatchlist().

Parameters:: account (MyPlexAccount, optional) – Account to check item on the watchlist. Note: This is required if you are not connected to a Plex server instance using the admin account.

addToWatchlist(account=None)[source]

Add this item to the specified user’s watchlist. Also see addToWatchlist().

Parameters:: account (MyPlexAccount, optional) – Account to add item to the watchlist. Note: This is required if you are not connected to a Plex server instance using the admin account.

removeFromWatchlist(account=None)[source]

Remove this item from the specified user’s watchlist. Also see removeFromWatchlist().

Parameters:: account (MyPlexAccount, optional) – Account to remove item from the watchlist. Note: This is required if you are not connected to a Plex server instance using the admin account.

streamingServices(account=None)[source]

Return a list of Availability objects for the available streaming services for this item.

Parameters:: account (MyPlexAccount, optional) – Account used to retrieve availability. Note: This is required if you are not connected to a Plex server instance using the admin account.

class plexapi.mixins.MovieEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, ContentRatingMixin, EditionTitleMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin, SummaryMixin, TaglineMixin, TitleMixin, UserRatingMixin, CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin

class plexapi.mixins.ShowEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin, SummaryMixin, TaglineMixin, TitleMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin

class plexapi.mixins.SeasonEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, LabelMixin

class plexapi.mixins.EpisodeEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, ContentRatingMixin, OriginallyAvailableMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, DirectorMixin, LabelMixin, WriterMixin

class plexapi.mixins.ArtistEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin, SimilarArtistMixin, StyleMixin

class plexapi.mixins.AlbumEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, OriginallyAvailableMixin, SortTitleMixin, StudioMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin, MoodMixin, StyleMixin

class plexapi.mixins.TrackEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, TitleMixin, TrackArtistMixin, TrackNumberMixin, TrackDiscNumberMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin, MoodMixin

class plexapi.mixins.PhotoalbumEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, AddedAtMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin

class plexapi.mixins.PhotoEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, AddedAtMixin, PhotoCapturedTimeMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, TagMixin

class plexapi.mixins.CollectionEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, ContentRatingMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, LabelMixin

class plexapi.mixins.PlaylistEditMixins[source]: Bases: ArtLockMixin, PosterLockMixin, SortTitleMixin, SummaryMixin, TitleMixin

MyPlex plexapi.myplex

class plexapi.myplex.MyPlexAccount(username=None, password=None, token=None, session=None, timeout=None, code=None, remember=True)[source]

Bases: PlexObject

MyPlex account and profile information. This object represents the data found Account on the myplex.tv servers at the url https://plex.tv/api/v2/user. You may create this object directly by passing in your username & password (or token). There is also a convenience method provided at myPlexAccount() which will create and return this object.

Parameters:

username (str) – Plex login username if not using a token.
password (str) – Plex login password if not using a token.
token (str) – Plex authentication token instead of username and password.
session (requests.Session, optional) – Use your own session object if you want to cache the http responses from PMS.
timeout (int) – timeout in seconds on initial connect to myplex (default config.TIMEOUT).
code (str) – Two-factor authentication code to use when logging in with username and password.
remember (bool) – Remember the account token for 14 days (Default True).

Variables:

key (str) – ‘https://plex.tv/api/v2/user’
adsConsent (str) – Unknown.
adsConsentReminderAt (str) – Unknown.
adsConsentSetAt (str) – Unknown.
anonymous (str) – Unknown.
authToken (str) – The account token.
backupCodesCreated (bool) – If the two-factor authentication backup codes have been created.
confirmed (bool) – If the account has been confirmed.
country (str) – The account country.
email (str) – The account email address.
emailOnlyAuth (bool) – If login with email only is enabled.
experimentalFeatures (bool) – If experimental features are enabled.
friendlyName (str) – Your account full name.
entitlements (List<str>) – List of devices your allowed to use with this account.
guest (bool) – If the account is a Plex Home guest user.
hasPassword (bool) – If the account has a password.
home (bool) – If the account is a Plex Home user.
homeAdmin (bool) – If the account is the Plex Home admin.
homeSize (int) – The number of accounts in the Plex Home.
id (int) – The Plex account ID.
joinedAt (datetime) – Date the account joined Plex.
locale (str) – the account locale
mailingListActive (bool) – If you are subscribed to the Plex newsletter.
mailingListStatus (str) – Your current mailing list status.
maxHomeSize (int) – The maximum number of accounts allowed in the Plex Home.
pin (str) – The hashed Plex Home PIN.
profileAutoSelectAudio (bool) – If the account has automatically select audio and subtitle tracks enabled.
profileDefaultAudioLanguage (str) – The preferred audio language for the account.
profileDefaultSubtitleLanguage (str) – The preferred subtitle language for the account.
profileAutoSelectSubtitle (int) – The auto-select subtitle mode (0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled).
profileDefaultSubtitleAccessibility (int) – The subtitles for the deaf or hard-of-hearing (SDH) searches mode (0 = Prefer non-SDH subtitles, 1 = Prefer SDH subtitles, 2 = Only show SDH subtitles, 3 = Only shown non-SDH subtitles).
profileDefaultSubtitleForced (int) – The forced subtitles searches mode (0 = Prefer non-forced subtitles, 1 = Prefer forced subtitles, 2 = Only show forced subtitles, 3 = Only show non-forced subtitles).
protected (bool) – If the account has a Plex Home PIN enabled.
rememberExpiresAt (datetime) – Date the token expires.
restricted (bool) – If the account is a Plex Home managed user.
roles – (List<str>) Lit of account roles. Plexpass membership listed here.
scrobbleTypes (List<int>) – Unknown.
subscriptionActive (bool) – If the account’s Plex Pass subscription is active.
subscriptionDescription (str) – Description of the Plex Pass subscription.
subscriptionFeatures – (List<str>) List of features allowed on your Plex Pass subscription.
subscriptionPaymentService (str) – Payment service used for your Plex Pass subscription.
subscriptionPlan (str) – Name of Plex Pass subscription plan.
subscriptionStatus (str) – String representation of subscriptionActive.
subscriptionSubscribedAt (datetime) – Date the account subscribed to Plex Pass.
thumb (str) – URL of the account thumbnail.
title (str) – The title of the account (username or friendly name).
twoFactorEnabled (bool) – If two-factor authentication is enabled.
username (str) – The account username.
uuid (str) – The account UUID.

signout()[source]: Sign out of the Plex account. Invalidates the authentication token.

property authenticationToken: Returns the authentication token for the account. Alias for authToken.

ping()[source]: Ping the Plex.tv API. This will refresh the authentication token to prevent it from expiring.

device(name=None, clientId=None)[source]

Returns the MyPlexDevice that matches the name specified.

Parameters:

name (str) – Name to match against.
clientId (str) – clientIdentifier to match against.

devices()[source]: Returns a list of all MyPlexDevice objects connected to the server.

resource(name)[source]

Returns the MyPlexResource that matches the name specified.

Parameters:: name (str) – Name to match against.

resources()[source]: Returns a list of all MyPlexResource objects connected to the server.

inviteFriend(user, server, sections=None, allowSync=False, allowCameraUpload=False, allowChannels=False, filterMovies=None, filterTelevision=None, filterMusic=None)[source]

Share library content with the specified user.

Parameters:

user (MyPlexUser) – MyPlexUser object, username, or email of the user to be added.
server (PlexServer) – PlexServer object, or machineIdentifier containing the library sections to share.
sections (List<LibrarySection>) – List of LibrarySection objects, or names to be shared (default None). sections must be defined in order to update shared libraries.
allowSync (Bool) – Set True to allow user to sync content.
allowCameraUpload (Bool) – Set True to allow user to upload photos.
allowChannels (Bool) – Set True to allow user to utilize installed channels.
filterMovies (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterTelevision (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterMusic (Dict) – Dict containing key ‘label’ set to a list of values to be filtered. ex: {‘label’:[‘foo’]}

createHomeUser(user, server, sections=None, allowSync=False, allowCameraUpload=False, allowChannels=False, filterMovies=None, filterTelevision=None, filterMusic=None)[source]

Share library content with the specified user.

Parameters:

user (MyPlexUser) – MyPlexUser object, username, or email of the user to be added.
server (PlexServer) – PlexServer object, or machineIdentifier containing the library sections to share.
sections (List<LibrarySection>) – List of LibrarySection objects, or names to be shared (default None). sections must be defined in order to update shared libraries.
allowSync (Bool) – Set True to allow user to sync content.
allowCameraUpload (Bool) – Set True to allow user to upload photos.
allowChannels (Bool) – Set True to allow user to utilize installed channels.
filterMovies (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterTelevision (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterMusic (Dict) – Dict containing key ‘label’ set to a list of values to be filtered. ex: {‘label’:[‘foo’]}

createExistingUser(user, server, sections=None, allowSync=False, allowCameraUpload=False, allowChannels=False, filterMovies=None, filterTelevision=None, filterMusic=None)[source]

Share library content with the specified user.

Parameters:

user (MyPlexUser) – MyPlexUser object, username, or email of the user to be added.
server (PlexServer) – PlexServer object, or machineIdentifier containing the library sections to share.
sections (List<LibrarySection>) – List of LibrarySection objects, or names to be shared (default None). sections must be defined in order to update shared libraries.
allowSync (Bool) – Set True to allow user to sync content.
allowCameraUpload (Bool) – Set True to allow user to upload photos.
allowChannels (Bool) – Set True to allow user to utilize installed channels.
filterMovies (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterTelevision (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterMusic (Dict) – Dict containing key ‘label’ set to a list of values to be filtered. ex: {‘label’:[‘foo’]}

removeFriend(user)[source]

Remove the specified user from your friends.

Parameters:: user (MyPlexUser or str) – MyPlexUser, username, or email of the user to be removed.

removeHomeUser(user)[source]

Remove the specified user from your home users.

Parameters:: user (MyPlexUser or str) – MyPlexUser, username, or email of the user to be removed.

switchHomeUser(user, pin=None)[source]

Returns a new MyPlexAccount object switched to the given home user.

Parameters:

user (MyPlexUser or str) – MyPlexUser, username, or email of the home user to switch to.
pin (str) – PIN for the home user (required if the home user has a PIN set).

Example

from plexapi.myplex import MyPlexAccount
# Login to a Plex Home account
account = MyPlexAccount('<USERNAME>', '<PASSWORD>')
# Switch to a different Plex Home user
userAccount = account.switchHomeUser('Username')

setPin(newPin, currentPin=None)[source]

Set a new Plex Home PIN for the account.

Parameters:

newPin (str) – New PIN to set for the account.
currentPin (str) – Current PIN for the account (required to change the PIN).

removePin(currentPin)[source]

Remove the Plex Home PIN for the account.

Parameters:: currentPin (str) – Current PIN for the account (required to remove the PIN).

setManagedUserPin(user, newPin)[source]

Set a new Plex Home PIN for a managed home user. This must be done from the Plex Home admin account.

Parameters:

user (MyPlexUser or str) – MyPlexUser or username of the managed home user.
newPin (str) – New PIN to set for the managed home user.

removeManagedUserPin(user)[source]

Remove the Plex Home PIN for a managed home user. This must be done from the Plex Home admin account.

Parameters:: user (MyPlexUser or str) – MyPlexUser or username of the managed home user.

acceptInvite(user)[source]

Accept a pending friend invite from the specified user.

Parameters:: user (MyPlexInvite or str) – MyPlexInvite, username, or email of the friend invite to accept.

cancelInvite(user)[source]

Cancel a pending firend invite for the specified user.

Parameters:: user (MyPlexInvite or str) – MyPlexInvite, username, or email of the friend invite to cancel.

updateFriend(user, server, sections=None, removeSections=False, allowSync=None, allowCameraUpload=None, allowChannels=None, filterMovies=None, filterTelevision=None, filterMusic=None)[source]

Update the specified user’s share settings.

Parameters:

user (MyPlexUser) – MyPlexUser object, username, or email of the user to be updated.
server (PlexServer) – PlexServer object, or machineIdentifier containing the library sections to share.
sections (List<LibrarySection>) – List of LibrarySection objects, or names to be shared (default None). sections must be defined in order to update shared libraries.
removeSections (Bool) – Set True to remove all shares. Supersedes sections.
allowSync (Bool) – Set True to allow user to sync content.
allowCameraUpload (Bool) – Set True to allow user to upload photos.
allowChannels (Bool) – Set True to allow user to utilize installed channels.
filterMovies (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterTelevision (Dict) – Dict containing key ‘contentRating’ and/or ‘label’ each set to a list of values to be filtered. ex: {‘contentRating’:[‘G’], ‘label’:[‘foo’]}
filterMusic (Dict) – Dict containing key ‘label’ set to a list of values to be filtered. ex: {‘label’:[‘foo’]}

user(username)[source]

Returns the MyPlexUser that matches the specified username or email.

Parameters:: username (str) – Username, email or id of the user to return.

users()[source]: Returns a list of all MyPlexUser objects connected to your account.

pendingInvite(username, includeSent=True, includeReceived=True)[source]

Returns the MyPlexInvite that matches the specified username or email. Note: This can be a pending invite sent from your account or received to your account.

Parameters:

username (str) – Username, email or id of the user to return.
includeSent (bool) – True to include sent invites.
includeReceived (bool) – True to include received invites.

pendingInvites(includeSent=True, includeReceived=True)[source]

Returns a list of all MyPlexInvite objects connected to your account. Note: This includes all pending invites sent from your account and received to your account.

Parameters:

includeSent (bool) – True to include sent invites.
includeReceived (bool) – True to include received invites.

optOut(playback=None, library=None)[source]: Opt in or out of sharing stuff with plex. See: https://www.plex.tv/about/privacy-legal/

syncItems(client=None, clientId=None)[source]

Returns an instance of SyncList for specified client.

Parameters:

client (MyPlexDevice) – a client to query SyncItems for.
clientId (str) – an identifier of a client to query SyncItems for.

If both client and clientId provided the client would be preferred. If neither client nor clientId provided the clientId would be set to current clients’s identifier.

sync(sync_item, client=None, clientId=None)[source]

Adds specified sync item for the client. It’s always easier to use methods defined directly in the media objects, e.g. sync(), sync().

Parameters:

client (MyPlexDevice) – a client for which you need to add SyncItem to.
clientId (str) – an identifier of a client for which you need to add SyncItem to.
sync_item (SyncItem) – prepared SyncItem object with all fields set.

If both client and clientId provided the client would be preferred. If neither client nor clientId provided the clientId would be set to current clients’s identifier.

Returns:

an instance of created syncItem.

Return type:

Raises:

BadRequest – When client with provided clientId wasn’t found.
BadRequest – Provided client doesn’t provides sync-target.

claimToken()[source]: Returns a str, a new “claim-token”, which you can use to register your new Plex Server instance to your account. See: https://hub.docker.com/r/plexinc/pms-docker/, https://www.plex.tv/claim/

history(maxresults=None, mindate=None)[source]

Get Play History for all library sections on all servers for the owner.

Parameters:

maxresults (int) – Only return the specified number of results (optional).
mindate (datetime) – Min datetime to return results from.

onlineMediaSources()[source]: Returns a list of user account Online Media Sources settings AccountOptOut

videoOnDemand()[source]: Returns a list of VOD Hub items Hub

tidal()[source]: Returns a list of tidal Hub items Hub

watchlist(filter=None, sort=None, libtype=None, maxresults=None, **kwargs)[source]

Returns a list of Movie and Show items in the user’s watchlist. Note: The objects returned are from Plex’s online metadata. To get the matching item on a Plex server, search for the media using the guid.

Parameters:

filter (str, optional) – ‘available’ or ‘released’ to only return items that are available or released, otherwise return all items.
sort (str, optional) – In the format field:dir. Available fields are watchlistedAt (Added At), titleSort (Title), originallyAvailableAt (Release Date), or rating (Critic Rating). dir can be asc or desc.
libtype (str, optional) – ‘movie’ or ‘show’ to only return movies or shows, otherwise return all items.
maxresults (int, optional) – Only return the specified number of results.
**kwargs (dict) – Additional custom filters to apply to the search results.

Example

# Watchlist for released movies sorted by critic rating in descending order
watchlist = account.watchlist(filter='released', sort='rating:desc', libtype='movie')
item = watchlist[0]  # First item in the watchlist

# Search for the item on a Plex server
result = plex.library.search(guid=item.guid, libtype=item.type)

onWatchlist(item)[source]

Returns True if the item is on the user’s watchlist.

Parameters:: item (Movie or Show) – Item to check if it is on the user’s watchlist.

addToWatchlist(items)[source]

Add media items to the user’s watchlist

Parameters:: items (List) – List of Movie or Show objects to be added to the watchlist.
Raises:: BadRequest – When trying to add invalid or existing media to the watchlist.

removeFromWatchlist(items)[source]

Remove media items from the user’s watchlist

Parameters:: items (List) – List of Movie or Show objects to be added to the watchlist.
Raises:: BadRequest – When trying to remove invalid or non-existing media to the watchlist.

userState(item)[source]

Returns a UserState object for the specified item.

Parameters:: item (Movie or Show) – Item to return the user state.

isPlayed(item)[source]

Return True if the item is played on Discover.

:param item (Movie: :param : :param Show: :param Season or: :param Episode): Object from searchDiscover(). :param Can be also result from Plex Movie or Plex TV Series agent.:

markPlayed(item)[source]

Mark the Plex object as played on Discover.

:param item (Movie: :param : :param Show: :param Season or: :param Episode): Object from searchDiscover(). :param Can be also result from Plex Movie or Plex TV Series agent.:

markUnplayed(item)[source]

Mark the Plex object as unplayed on Discover.

:param item (Movie: :param : :param Show: :param Season or: :param Episode): Object from searchDiscover(). :param Can be also result from Plex Movie or Plex TV Series agent.:

searchDiscover(query, limit=30, libtype=None)[source]

Search for movies and TV shows in Discover. Returns a list of Movie and Show objects.

Parameters:

query (str) – Search query.
limit (int, optional) – Limit to the specified number of results. Default 30.
libtype (str, optional) – ‘movie’ or ‘show’ to only return movies or shows, otherwise return all items.

property viewStateSync: Returns True or False if syncing of watch state and ratings is enabled or disabled, respectively, for the account.

enableViewStateSync()[source]: Enable syncing of watch state and ratings for the account.

disableViewStateSync()[source]: Disable syncing of watch state and ratings for the account.

link(pin)[source]

Link a device to the account using a pin code.

Parameters:: pin (str) – The 4 digit link pin code.

publicIP()[source]: Returns your public IP address.

geoip(ip_address)[source]

Returns a GeoLocation object with geolocation information for an IP address using Plex’s GeoIP database.

Parameters:: ip_address (str) – IP address to lookup.

class plexapi.myplex.MyPlexUser(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

This object represents non-signed in users such as friends and linked accounts. NOTE: This should not be confused with the MyPlexAccount which is your specific account. The raw xml for the data presented here can be found at: https://plex.tv/api/users/

Variables:

TAG (str) – ‘User’
key (str) – ‘https://plex.tv/api/users/’
allowCameraUpload (bool) – True if this user can upload images.
allowChannels (bool) – True if this user has access to channels.
allowSync (bool) – True if this user can sync.
email (str) – User’s email address (user@gmail.com).
filterAll (str) – Unknown.
filterMovies (str) – Unknown.
filterMusic (str) – Unknown.
filterPhotos (str) – Unknown.
filterTelevision (str) – Unknown.
home (bool) – Unknown.
id (int) – User’s Plex account ID.
protected (False) – Unknown (possibly SSL enabled?).
recommendationsPlaylistId (str) – Unknown.
restricted (str) – Unknown.
servers (List<<MyPlexServerShare>)) – Servers shared with the user.
thumb (str) – Link to the users avatar.
title (str) – Seems to be an alias for username.
username (str) – User’s username.

server(name)[source]

Returns the MyPlexServerShare that matches the name specified.

Parameters:: name (str) – Name of the server to return.

history(maxresults=None, mindate=None)[source]: Get all Play History for a user in all shared servers. :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime

class plexapi.myplex.MyPlexInvite(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

This object represents pending friend invites.

Variables:

TAG (str) – ‘Invite’
createdAt (datetime) – Datetime the user was invited.
email (str) – User’s email address (user@gmail.com).
friend (bool) – True or False if the user is invited as a friend.
friendlyName (str) – The user’s friendly name.
home (bool) – True or False if the user is invited to a Plex Home.
id (int) – User’s Plex account ID.
server (bool) – True or False if the user is invited to any servers.
servers (List<<MyPlexServerShare>)) – Servers shared with the user.
thumb (str) – Link to the users avatar.
username (str) – User’s username.

class plexapi.myplex.Section(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

This refers to a shared section. The raw xml for the data presented here can be found at: https://plex.tv/api/servers/{machineId}/shared_servers

Variables:

TAG (str) – section
id (int) – The shared section ID
key (int) – The shared library section key
shared (bool) – If this section is shared with the user
title (str) – Title of the section
type (str) – movie, tvshow, artist

history(maxresults=None, mindate=None)[source]: Get all Play History for a user for this section in this shared server. :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime

class plexapi.myplex.MyPlexServerShare(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single user’s server reference. Used for library sharing.

Variables:

id (int) – id for this share
serverId (str) – what id plex uses for this.
machineIdentifier (str) – The servers machineIdentifier
name (str) – The servers name
lastSeenAt (datetime) – Last connected to the server?
numLibraries (int) – Total number of libraries
allLibraries (bool) – True if all libraries is shared with this user.
owned (bool) – 1 if the server is owned by the user
pending (bool) – True if the invite is pending.

section(name)[source]

Returns the Section that matches the name specified.

Parameters:: name (str) – Name of the section to return.

sections()[source]: Returns a list of all Section objects shared with this user.

history(maxresults=9999999, mindate=None)[source]: Get all Play History for a user in this shared server. :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime

class plexapi.myplex.MyPlexResource(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

This object represents resources connected to your Plex server that can provide content such as Plex Media Servers, iPhone or Android clients, etc. The raw xml for the data presented here can be found at: https://plex.tv/api/v2/resources?includeHttps=1&includeRelay=1

Variables:

TAG (str) – ‘Device’
key (str) – ‘https://plex.tv/api/v2/resources?includeHttps=1&includeRelay=1’
accessToken (str) – This resource’s Plex access token.
clientIdentifier (str) – Unique ID for this resource.
connections (list) – List of ResourceConnection objects for this resource.
createdAt (datetime) – Timestamp this resource first connected to your server.
device (str) – Best guess on the type of device this is (PS, iPhone, Linux, etc).
dnsRebindingProtection (bool) – True if the server had DNS rebinding protection.
home (bool) – Unknown
httpsRequired (bool) – True if the resource requires https.
lastSeenAt (datetime) – Timestamp this resource last connected.
name (str) – Descriptive name of this resource.
natLoopbackSupported (bool) – True if the resource supports NAT loopback.
owned (bool) – True if this resource is one of your own (you logged into it).
ownerId (int) – ID of the user that owns this resource (shared resources only).
platform (str) – OS the resource is running (Linux, Windows, Chrome, etc.)
platformVersion (str) – Version of the platform.
presence (bool) – True if the resource is online
product (str) – Plex product (Plex Media Server, Plex for iOS, Plex Web, etc.)
productVersion (str) – Version of the product.
provides (str) – List of services this resource provides (client, server, player, pubsub-player, etc.)
publicAddressMatches (bool) – True if the public IP address matches the client’s public IP address.
relay (bool) – True if this resource has the Plex Relay enabled.
sourceTitle (str) – Username of the user that owns this resource (shared resources only).
synced (bool) – Unknown (possibly True if the resource has synced content?)

preferred_connections(ssl=None, locations=None, schemes=None)[source]

Returns a sorted list of the available connection addresses for this resource. Often times there is more than one address specified for a server or client. Default behavior will prioritize local connections before remote or relay and HTTPS before HTTP.

Parameters:: ssl (bool, optional) – Set True to only connect to HTTPS connections. Set False to only connect to HTTP connections. Set None (default) to connect to any HTTP or HTTPS connection.

connect(ssl=None, timeout=None, locations=None, schemes=None)[source]

Returns a new PlexServer or PlexClient object. Uses MyPlexResource.preferred_connections() to generate the priority order of connection addresses. After trying to connect to all available addresses for this resource and assuming at least one connection was successful, the PlexServer object is built and returned.

Parameters:

ssl (bool, optional) – Set True to only connect to HTTPS connections. Set False to only connect to HTTP connections. Set None (default) to connect to any HTTP or HTTPS connection.
timeout (int, optional) – The timeout in seconds to attempt each connection.

Raises:

NotFound – When unable to connect to any addresses for this resource.

class plexapi.myplex.ResourceConnection(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Resource Connection object found within the MyPlexResource objects.

Variables:

TAG (str) – ‘Connection’
address (str) – The connection IP address
httpuri (str) – Full HTTP URL
ipv6 (bool) – True if the address is IPv6
local (bool) – True if the address is local
port (int) – The connection port
protocol (str) – HTTP or HTTPS
relay (bool) – True if the address uses the Plex Relay
uri (str) – Full connetion URL

class plexapi.myplex.MyPlexDevice(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

This object represents resources connected to your Plex server that provide playback ability from your Plex Server, iPhone or Android clients, Plex Web, this API, etc. The raw xml for the data presented here can be found at: https://plex.tv/devices.xml

Variables:

TAG (str) – ‘Device’
key (str) – ‘https://plex.tv/devices.xml’
clientIdentifier (str) – Unique ID for this resource.
connections (list) – List of connection URIs for the device.
device (str) – Best guess on the type of device this is (Linux, iPad, AFTB, etc).
id (str) – MyPlex ID of the device.
model (str) – Model of the device (bueller, Linux, x86_64, etc.)
name (str) – Hostname of the device.
platform (str) – OS the resource is running (Linux, Windows, Chrome, etc.)
platformVersion (str) – Version of the platform.
product (str) – Plex product (Plex Media Server, Plex for iOS, Plex Web, etc.)
productVersion (string) – Version of the product.
provides (str) – List of services this resource provides (client, controller, sync-target, player, pubsub-player).
publicAddress (str) – Public IP address.
screenDensity (str) – Unknown
screenResolution (str) – Screen resolution (750x1334, 1242x2208, etc.)
token (str) – Plex authentication token for the device.
vendor (str) – Device vendor (ubuntu, etc).
version (str) – Unknown (1, 2, 1.3.3.3148-b38628e, 1.3.15, etc.)

connect(timeout=None)[source]

Returns a new PlexClient or PlexServer Sometimes there is more than one address specified for a server or client. After trying to connect to all available addresses for this client and assuming at least one connection was successful, the PlexClient object is built and returned.

Raises:: NotFound – When unable to connect to any addresses for this device.

delete()[source]: Remove this device from your account.

syncItems()[source]

Returns an instance of SyncList for current device.

Raises:: BadRequest – when the device doesn’t provides sync-target.

class plexapi.myplex.MyPlexPinLogin(session=None, requestTimeout=None, headers=None, oauth=False)[source]

Bases: object

MyPlex PIN login class which supports getting the four character PIN which the user must enter on https://plex.tv/link to authenticate the client and provide an access token to create a MyPlexAccount instance. This helper class supports a polling, threaded and callback approach.

The polling approach expects the developer to periodically check if the PIN login was successful using checkLogin().
The threaded approach expects the developer to call run() and then at a later time call waitForLogin() to wait for and check the result.
The callback approach is an extension of the threaded approach and expects the developer to pass the callback parameter to the call to run(). The callback will be called when the thread waiting for the PIN login to succeed either finishes or expires. The parameter passed to the callback is the received authentication token or None if the login expired.

Parameters:

session (requests.Session, optional) – Use your own session object if you want to cache the http responses from PMS
requestTimeout (int) – timeout in seconds on initial connect to plex.tv (default config.TIMEOUT).
headers (dict) – A dict of X-Plex headers to send with requests.
oauth (bool) – True to use Plex OAuth instead of PIN login.

Variables:

PINS (str) – ‘https://plex.tv/api/v2/pins’
CHECKPINS (str) – ‘https://plex.tv/api/v2/pins/{pinid}’
POLLINTERVAL (int) – 1
finished (bool) – Whether the pin login has finished or not.
expired (bool) – Whether the pin login has expired or not.
token (str) – Token retrieved through the pin login.
pin (str) – Pin to use for the login on https://plex.tv/link.

property pin: Return the 4 character PIN used for linking a device at https://plex.tv/link.

oauthUrl(forwardUrl=None)[source]

Return the Plex OAuth url for login.

Parameters:: forwardUrl (str, optional) – The url to redirect the client to after login.

run(callback=None, timeout=None)[source]

Starts the thread which monitors the PIN login state.

Parameters:

callback (Callable[str]) – Callback called with the received authentication token (optional).
timeout (int) – Timeout in seconds waiting for the PIN login to succeed (optional).

Raises:

RuntimeError – If the thread is already running.
RuntimeError – If the PIN login for the current PIN has expired.

waitForLogin()[source]

Waits for the PIN login to succeed or expire.

Parameters:

callback (Callable[str]) – Callback called with the received authentication token (optional).
timeout (int) – Timeout in seconds waiting for the PIN login to succeed (optional).

Returns:

True if the PIN login succeeded or False otherwise.

stop()[source]: Stops the thread monitoring the PIN login state.

checkLogin()[source]: Returns True if the PIN login has succeeded.

class plexapi.myplex.AccountOptOut(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single AccountOptOut ‘https://plex.tv/api/v2/user/{userUUID}/settings/opt_outs’

Variables:

TAG (str) – optOut
key (str) – Online Media Source key
value (str) – Online Media Source opt_in, opt_out, or opt_out_managed

optIn()[source]: Sets the Online Media Source to “Enabled”.

optOut()[source]: Sets the Online Media Source to “Disabled”.

optOutManaged()[source]

Sets the Online Media Source to “Disabled for Managed Users”.

Raises:: BadRequest – When trying to opt out music.

class plexapi.myplex.UserState(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single UserState

Variables:

TAG (str) – UserState
lastViewedAt (datetime) – Datetime the item was last played.
ratingKey (str) – Unique key identifying the item.
type (str) – The media type of the item.
viewCount (int) – Count of times the item was played.
viewedLeafCount (int) – Number of items marked as played in the show/season.
viewOffset (int) – Time offset in milliseconds from the start of the content
viewState (bool) – True or False if the item has been played.
watchlistedAt (datetime) – Datetime the item was added to the watchlist.

class plexapi.myplex.GeoLocation(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a signle IP address geolocation

Variables:

TAG (str) – location
city (str) – City name
code (str) – Country code
continentCode (str) – Continent code
coordinates (Tuple<float>) – Latitude and longitude
country (str) – Country name
europeanUnionMember (bool) – True if the country is a member of the European Union
inPrivacyRestrictedCountry (bool) – True if the country is privacy restricted
postalCode (str) – Postal code
subdivisions (str) – Subdivision name
timezone (str) – Timezone

Photo plexapi.photo

class plexapi.photo.Photoalbum(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, RatingMixin, ArtMixin, PosterMixin, PhotoalbumEditMixins

Represents a single Photoalbum (collection of photos).

Variables:

TAG (str) – ‘Directory’
TYPE (str) – ‘photo’
addedAt (datetime) – Datetime the photo album was added to the library.
art (str) – URL to artwork image (/library/metadata/<ratingKey>/art/<artid>).
composite (str) – URL to composite image (/library/metadata/<ratingKey>/composite/<compositeid>)
fields (List<Field>) – List of field objects.
guid (str) – Plex GUID for the photo album (local://229674).
index (sting) – Plex index number for the photo album.
key (str) – API URL (/library/metadata/<ratingkey>).
lastRatedAt (datetime) – Datetime the photo album was last rated.
librarySectionID (int) – LibrarySection ID.
librarySectionKey (str) – LibrarySection key.
librarySectionTitle (str) – LibrarySection title.
listType (str) – Hardcoded as ‘photo’ (useful for search filters).
ratingKey (int) – Unique key identifying the photo album.
summary (str) – Summary of the photoalbum.
thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
title (str) – Name of the photo album. (Trip to Disney World)
titleSort (str) – Title to use when sorting (defaults to title).
type (str) – ‘photo’
updatedAt (datetime) – Datetime the photo album was updated.
userRating (float) – Rating of the photo album (0.0 - 10.0) equaling (0 stars - 5 stars).

album(title)[source]

Returns the Photoalbum that matches the specified title.

Parameters:: title (str) – Title of the photo album to return.

albums(**kwargs)[source]: Returns a list of Photoalbum objects in the album.

photo(title)[source]

Returns the Photo that matches the specified title.

Parameters:: title (str) – Title of the photo to return.

photos(**kwargs)[source]: Returns a list of Photo objects in the album.

clip(title)[source]

Returns the Clip that matches the specified title.

Parameters:: title (str) – Title of the clip to return.

clips(**kwargs)[source]: Returns a list of Clip objects in the album.

get(title)[source]: Alias to photo().

download(savepath=None, keep_original_name=False, subfolders=False)[source]

Download all photos and clips from the photo album. See download() for details.

Parameters:

savepath (str) – Defaults to current working dir.
keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated.
subfolders (bool) – True to separate photos/clips in to photo album folders.

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.photo.Photo(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, Playable, RatingMixin, ArtUrlMixin, PosterUrlMixin, PhotoEditMixins

Represents a single Photo.

Variables:

TAG (str) – ‘Photo’
TYPE (str) – ‘photo’
addedAt (datetime) – Datetime the photo was added to the library.
createdAtAccuracy (str) – Unknown (local).
createdAtTZOffset (int) – Unknown (-25200).
fields (List<Field>) – List of field objects.
guid (str) – Plex GUID for the photo (com.plexapp.agents.none://231714?lang=xn).
index (sting) – Plex index number for the photo.
key (str) – API URL (/library/metadata/<ratingkey>).
lastRatedAt (datetime) – Datetime the photo was last rated.
librarySectionID (int) – LibrarySection ID.
librarySectionKey (str) – LibrarySection key.
librarySectionTitle (str) – LibrarySection title.
listType (str) – Hardcoded as ‘photo’ (useful for search filters).
media (List<Media>) – List of media objects.
originallyAvailableAt (datetime) – Datetime the photo was added to Plex.
parentGuid (str) – Plex GUID for the photo album (local://229674).
parentIndex (int) – Plex index number for the photo album.
parentKey (str) – API URL of the photo album (/library/metadata/<parentRatingKey>).
parentRatingKey (int) – Unique key identifying the photo album.
parentThumb (str) – URL to photo album thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
parentTitle (str) – Name of the photo album for the photo.
ratingKey (int) – Unique key identifying the photo.
sourceURI (str) – Remote server URI (server://<machineIdentifier>/com.plexapp.plugins.library) (remote playlist item only).
summary (str) – Summary of the photo.
tags (List<Tag>) – List of tag objects.
thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
title (str) – Name of the photo.
titleSort (str) – Title to use when sorting (defaults to title).
type (str) – ‘photo’
updatedAt (datetime) – Datetime the photo was updated.
userRating (float) – Rating of the photo (0.0 - 10.0) equaling (0 stars - 5 stars).
year (int) – Year the photo was taken.

photoalbum()[source]: Return the photo’s Photoalbum.

section()[source]: Returns the LibrarySection the item belongs to.

property locations

This does not exist in plex xml response but is added to have a common interface to get the locations of the photo.

Returns:: List<str> of file paths where the photo is found on disk.

sync(resolution, client=None, clientId=None, limit=None, title=None)[source]

Add current photo as sync item for specified device. See sync() for possible exceptions.

Parameters:

resolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync.
client (MyPlexDevice) – sync destination, see sync().
clientId (str) – sync destination, see sync().
limit (int) – maximum count of items to sync, unlimited if None.
title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current photo.

Returns:

an instance of created syncItem.

Return type:

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.photo.PhotoSession(server, data, initpath=None, parent=None)[source]

Bases: PlexSession, Photo

Represents a single Photo session loaded from sessions().

Playlist plexapi.playlist

class plexapi.playlist.Playlist(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, Playable, SmartFilterMixin, ArtMixin, PosterMixin, PlaylistEditMixins

Represents a single Playlist.

Variables:

TAG (str) – ‘Playlist’
TYPE (str) – ‘playlist’
addedAt (datetime) – Datetime the playlist was added to the server.
allowSync (bool) – True if you allow syncing playlists.
composite (str) – URL to composite image (/playlist/<ratingKey>/composite/<compositeid>)
content (str) – The filter URI string for smart playlists.
duration (int) – Duration of the playlist in milliseconds.
durationInSeconds (int) – Duration of the playlist in seconds.
fields (List<Field>) – List of field objects.
guid (str) – Plex GUID for the playlist (com.plexapp.agents.none://XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX).
icon (str) – Icon URI string for smart playlists.
key (str) – API URL (/playlist/<ratingkey>).
leafCount (int) – Number of items in the playlist view.
librarySectionID (int) – Library section identifier (radio only)
librarySectionKey (str) – Library section key (radio only)
librarySectionTitle (str) – Library section title (radio only)
playlistType (str) – ‘audio’, ‘video’, or ‘photo’
radio (bool) – If this playlist represents a radio station
ratingKey (int) – Unique key identifying the playlist.
smart (bool) – True if the playlist is a smart playlist.
summary (str) – Summary of the playlist.
title (str) – Name of the playlist.
titleSort (str) – Title to use when sorting (defaults to title).
type (str) – ‘playlist’
updatedAt (datetime) – Datetime the playlist was updated.

property thumb: Alias to self.composite.

property metadataType: Returns the type of metadata in the playlist (movie, track, or photo).

property isVideo: Returns True if this is a video playlist.

property isAudio: Returns True if this is an audio playlist.

property isPhoto: Returns True if this is a photo playlist.

filters()[source]: Returns the search filter dict for smart playlist. The filter dict be passed back into search() to get the list of items.

section()[source]

Returns the LibrarySection this smart playlist belongs to.

Raises:

plexapi.exceptions.BadRequest – When trying to get the section for a regular playlist.
plexapi.exceptions.Unsupported – When unable to determine the library section.

item(title)[source]

Returns the item in the playlist that matches the specified title.

Parameters:: title (str) – Title of the item to return.
Raises:: plexapi.exceptions.NotFound – When the item is not found in the playlist.

items()[source]: Returns a list of all items in the playlist.

get(title)[source]: Alias to item().

addItems(items)[source]

Add items to the playlist.

Parameters:: items (List) – List of Audio, Video, or Photo objects to be added to the playlist.
Raises:: plexapi.exceptions.BadRequest – When trying to add items to a smart playlist.

removeItems(items)[source]

Remove items from the playlist.

Parameters:

items (List) – List of Audio, Video, or Photo objects to be removed from the playlist.

Raises:

plexapi.exceptions.BadRequest – When trying to remove items from a smart playlist.
plexapi.exceptions.NotFound – When the item does not exist in the playlist.

moveItem(item, after=None)[source]

Move an item to a new position in the playlist.

Parameters:

items (obj) – Audio, Video, or Photo objects to be moved in the playlist.
after (obj) – Audio, Video, or Photo objects to move the item after in the playlist.

Raises:

plexapi.exceptions.BadRequest – When trying to move items in a smart playlist.
plexapi.exceptions.NotFound – When the item or item after does not exist in the playlist.

updateFilters(limit=None, sort=None, filters=None, **kwargs)[source]

Update the filters for a smart playlist.

Parameters:

limit (int) – Limit the number of items in the playlist.
sort (str or list, optional) – A string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – A dictionary of advanced filters. See search() for more info.
**kwargs (dict) – Additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When trying update filters for a regular playlist.

edit(title=None, summary=None)[source]

Edit the playlist.

Parameters:

title (str, optional) – The title of the playlist.
summary (str, optional) – The summary of the playlist.

delete()[source]: Delete the playlist.

classmethod create(server, title, section=None, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, m3ufilepath=None, **kwargs)[source]

Create a playlist.

Parameters:

server (PlexServer) – Server to create the playlist on.
title (str) – Title of the playlist.
section (LibrarySection, str) – Smart playlists and m3u import only, the library section to create the playlist in.
items (List) – Regular playlists only, list of Audio, Video, or Photo objects to be added to the playlist.
smart (bool) – True to create a smart playlist. Default False.
limit (int) – Smart playlists only, limit the number of items in the playlist.
libtype (str) – Smart playlists only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).
sort (str or list, optional) – Smart playlists only, a string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – Smart playlists only, a dictionary of advanced filters. See search() for more info.
m3ufilepath (str) – Music playlists only, the full file path to an m3u file to import. Note: This will overwrite any playlist previously created from the same m3u file.
**kwargs (dict) – Smart playlists only, additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When no items are included to create the playlist.
plexapi.exceptions.BadRequest – When mixing media types in the playlist.
plexapi.exceptions.BadRequest – When attempting to import m3u file into non-music library.
plexapi.exceptions.BadRequest – When failed to import m3u file.

Returns:

A new instance of the created Playlist.

Return type:

Playlist

copyToUser(user)[source]

Copy playlist to another user account.

Parameters:: user (MyPlexUser or str) – MyPlexUser object, username, email, or user id of the user to copy the playlist to.

sync(videoQuality=None, photoResolution=None, audioBitrate=None, client=None, clientId=None, limit=None, unwatched=False, title=None)[source]

Add the playlist as a sync item for the specified device. See sync() for possible exceptions.

Parameters:

videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module. Used only when playlist contains video.
photoResolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync. Used only when playlist contains photos.
audioBitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync. Used only when playlist contains audio.
client (MyPlexDevice) – sync destination, see sync().
clientId (str) – sync destination, see sync().
limit (int) – maximum count of items to sync, unlimited if None.
unwatched (bool) – if True watched videos wouldn’t be synced.
title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current photo.

Raises:

BadRequest – When playlist is not allowed to sync.
Unsupported – When playlist content is unsupported.

Returns:

A new instance of the created sync item.

Return type:

property metadataDirectory: Returns the Plex Media Server data directory where the metadata is stored.

Playqueue plexapi.playqueue

class plexapi.playqueue.PlayQueue(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Control a PlayQueue.

Variables:

TAG (str) – ‘PlayQueue’
TYPE (str) – ‘playqueue’
identifier (str) – com.plexapp.plugins.library
items (list) – List of Playable or Playlist
mediaTagPrefix (str) – Fx /system/bundle/media/flags/
mediaTagVersion (int) – Fx 1485957738
playQueueID (int) – ID of the PlayQueue.
playQueueLastAddedItemID (int) – Defines where the “Up Next” region starts. Empty unless PlayQueue is modified after creation.
playQueueSelectedItemID (int) – The queue item ID of the currently selected item.
playQueueSelectedItemOffset (int) – The offset of the selected item in the PlayQueue, from the beginning of the queue.
playQueueSelectedMetadataItemID (int) – ID of the currently selected item, matches ratingKey.
playQueueShuffled (bool) – True if shuffled.
playQueueSourceURI (str) – Original URI used to create the PlayQueue.
playQueueTotalCount (int) – How many items in the PlayQueue.
playQueueVersion (int) – Version of the PlayQueue. Increments every time a change is made to the PlayQueue.
selectedItem (Playable) – Media object for the currently selected item.
_server (PlexServer) – PlexServer associated with the PlayQueue.
size (int) – Alias for playQueueTotalCount.

getQueueItem(item)[source]: Accepts a media item and returns a similar object from this PlayQueue. Useful for looking up playQueueItemIDs using items obtained from the Library.

classmethod get(server, playQueueID, own=False, center=None, window=50, includeBefore=True, includeAfter=True)[source]

Retrieve an existing PlayQueue by identifier.

Parameters:

server (PlexServer) – Server you are connected to.
playQueueID (int) – Identifier of an existing PlayQueue.
own (bool, optional) – If server should transfer ownership.
center (int, optional) – The playQueueItemID of the center of the window. Does not change selectedItem.
window (int, optional) – Number of items to return from each side of the center item.
includeBefore (bool, optional) – Include items before the center, defaults True. Does not include center if False.
includeAfter (bool, optional) – Include items after the center, defaults True. Does not include center if False.

classmethod create(server, items, startItem=None, shuffle=0, repeat=0, includeChapters=1, includeRelated=1, continuous=0)[source]

Create and return a new PlayQueue.

Parameters:

server (PlexServer) – Server you are connected to.
items (PlexPartialObject) – A media item or a list of media items.
startItem (Playable, optional) – Media item in the PlayQueue where playback should begin.
shuffle (int, optional) – Start the playqueue shuffled.
repeat (int, optional) – Start the playqueue shuffled.
includeChapters (int, optional) – include Chapters.
includeRelated (int, optional) – include Related.
continuous (int, optional) – include additional items after the initial item. For a show this would be the next episodes, for a movie it does nothing.

classmethod fromStationKey(server, key)[source]

Create and return a new PlayQueue.

This is a convenience method to create a PlayQueue for radio stations when only the key string is available.

Parameters:

server (PlexServer) – Server you are connected to.
key (str) – A station key as provided by hubs() or station()

Example

from plexapi.playqueue import PlayQueue
music = server.library.section("Music")
artist = music.get("Artist Name")
station = artist.station()
key = station.key  # "/library/metadata/12855/station/8bd39616-dbdb-459e-b8da-f46d0b170af4?type=10"
pq = PlayQueue.fromStationKey(server, key)
client = server.clients()[0]
client.playMedia(pq)

addItem(item, playNext=False, refresh=True)[source]

Append the provided item to the “Up Next” section of the PlayQueue. Items can only be added to the section immediately following the current playing item.

Parameters:

item (Playable or Playlist) – Single media item or Playlist.
playNext (bool, optional) – If True, add this item to the front of the “Up Next” section. If False, the item will be appended to the end of the “Up Next” section. Only has an effect if an item has already been added to the “Up Next” section. See https://support.plex.tv/articles/202188298-play-queues/ for more details.
refresh (bool, optional) – Refresh the PlayQueue from the server before updating.

moveItem(item, after=None, refresh=True)[source]

Moves an item to the beginning of the PlayQueue. If after is provided, the item will be placed immediately after the specified item.

Parameters:

item (Playable) – An existing item in the PlayQueue to move.
afterItemID (Playable, optional) – A different item in the PlayQueue. If provided, item will be placed in the PlayQueue after this item.
refresh (bool, optional) – Refresh the PlayQueue from the server before updating.

removeItem(item, refresh=True)[source]

Remove an item from the PlayQueue.

Parameters:

item (Playable) – An existing item in the PlayQueue to move.
refresh (bool, optional) – Refresh the PlayQueue from the server before updating.

clear()[source]: Remove all items from the PlayQueue.

refresh()[source]: Refresh the PlayQueue from the Plex server.

Server plexapi.server

class plexapi.server.PlexServer(baseurl=None, token=None, session=None, timeout=None)[source]

Bases: PlexObject

This is the main entry point to interacting with a Plex server. It allows you to list connected clients, browse your library sections and perform actions such as emptying trash. If you do not know the auth token required to access your Plex server, or simply want to access your server with your username and password, you can also create an PlexServer instance from MyPlexAccount.

Parameters:

baseurl (str) – Base url for to access the Plex Media Server (default: ‘http://localhost:32400’).
token (str) – Required Plex authentication token to access the server.
session (requests.Session, optional) – Use your own session object if you want to cache the http responses from the server.
timeout (int, optional) – Timeout in seconds on initial connection to the server (default config.TIMEOUT).

Variables:

allowCameraUpload (bool) – True if server allows camera upload.
allowChannelAccess (bool) – True if server allows channel access (iTunes?).
allowMediaDeletion (bool) – True is server allows media to be deleted.
allowSharing (bool) – True is server allows sharing.
allowSync (bool) – True is server allows sync.
backgroundProcessing (bool) – Unknown
certificate (bool) – True if server has an HTTPS certificate.
companionProxy (bool) – Unknown
diagnostics (bool) – Unknown
eventStream (bool) – Unknown
friendlyName (str) – Human friendly name for this server.
hubSearch (bool) – True if Hub Search is enabled. I believe this is enabled for everyone
machineIdentifier (str) – Unique ID for this server (looks like an md5).
multiuser (bool) – True if multiusers are enabled.
myPlex (bool) – Unknown (True if logged into myPlex?).
myPlexMappingState (str) – Unknown (ex: mapped).
myPlexSigninState (str) – Unknown (ex: ok).
myPlexSubscription (bool) – True if you have a myPlex subscription.
myPlexUsername (str) – Email address if signed into myPlex (user@example.com)
ownerFeatures (list) – List of features allowed by the server owner. This may be based on your PlexPass subscription. Features include: camera_upload, cloudsync, content_filter, dvr, hardware_transcoding, home, lyrics, music_videos, pass, photo_autotags, premium_music_metadata, session_bandwidth_restrictions, sync, trailers, webhooks (and maybe more).
photoAutoTag (bool) – True if photo auto-tagging is enabled.
platform (str) – Platform the server is hosted on (ex: Linux)
platformVersion (str) – Platform version (ex: ‘6.1 (Build 7601)’, ‘4.4.0-59-generic’).
pluginHost (bool) – Unknown
readOnlyLibraries (bool) – Unknown
requestParametersInCookie (bool) – Unknown
streamingBrainVersion (bool) – Current Streaming Brain version.
sync (bool) – True if syncing to a device is enabled.
transcoderActiveVideoSessions (int) – Number of active video transcoding sessions.
transcoderAudio (bool) – True if audio transcoding audio is available.
transcoderLyrics (bool) – True if audio transcoding lyrics is available.
transcoderPhoto (bool) – True if audio transcoding photos is available.
transcoderSubtitles (bool) – True if audio transcoding subtitles is available.
transcoderVideo (bool) – True if audio transcoding video is available.
transcoderVideoBitrates (bool) – List of video bitrates.
transcoderVideoQualities (bool) – List of video qualities.
transcoderVideoResolutions (bool) – List of video resolutions.
updatedAt (int) – Datetime the server was updated.
updater (bool) – Unknown
version (str) – Current Plex version (ex: 1.3.2.3112-1751929)
voiceSearch (bool) – True if voice search is enabled. (is this Google Voice search?)
_baseurl (str) – HTTP address of the client.
_token (str) – Token used to access this client.
_session (obj) – Requests session object used to access this client.

property library: Library to browse or search your media.

property settings: Returns a list of all server settings.

identity()[source]: Returns the Plex server identity.

account()[source]: Returns the Account object this server belongs to.

claim(account)[source]

Claim the Plex server using a MyPlexAccount. This will only work with an unclaimed server on localhost or the same subnet.

Parameters:: account (MyPlexAccount) – The account used to claim the server.

unclaim()[source]: Unclaim the Plex server. This will remove the server from your MyPlexAccount.

property activities: Returns all current PMS activities.

agents(mediaType=None)[source]: Returns a list of Agent objects this server has available.

createToken(type='delegation', scope='all')[source]: Create a temp access token for the server.

switchUser(user, session=None, timeout=None)[source]

Returns a new PlexServer object logged in as the given username. Note: Only the admin account can switch to other users.

Parameters:

user (MyPlexUser or str) – MyPlexUser object, username, email, or user id of the user to log in to the server.
session (requests.Session, optional) – Use your own session object if you want to cache the http responses from the server. This will default to the same session as the admin account if no new session is provided.
timeout (int, optional) – Timeout in seconds on initial connection to the server. This will default to the same timeout as the admin account if no new timeout is provided.

Example

from plexapi.server import PlexServer
# Login to the Plex server using the admin token
plex = PlexServer('http://plexserver:32400', token='2ffLuB84dqLswk9skLos')
# Login to the same Plex server using a different account
userPlex = plex.switchUser("Username")

systemAccounts()[source]: Returns a list of SystemAccount objects this server contains.

systemAccount(accountID)[source]

Returns the SystemAccount object for the specified account ID.

Parameters:: accountID (int) – The SystemAccount ID.

systemDevices()[source]: Returns a list of SystemDevice objects this server contains.

systemDevice(deviceID)[source]

Returns the SystemDevice object for the specified device ID.

Parameters:: deviceID (int) – The SystemDevice ID.

myPlexAccount()[source]: Returns a MyPlexAccount object using the same token to access this server. If you are not the owner of this PlexServer you’re likely to receive an authentication error calling this.

browse(path=None, includeFiles=True)[source]

Browse the system file path using the Plex API. Returns list of Path and File objects.

Parameters:

path (Path or str, optional) – Full path to browse.
includeFiles (bool) – True to include files when browsing (Default). False to only return folders.

walk(path=None)[source]

Walk the system file tree using the Plex API similar to os.walk. Yields a 3-tuple (path, paths, files) where path is a string of the directory path, paths is a list of Path objects, and files is a list of File objects.

Parameters:: path (Path or str, optional) – Full path to walk.

isBrowsable(path)[source]

Returns True if the Plex server can browse the given path.

Parameters:: path (Path or str) – Full path to browse.

clients()[source]: Returns list of all PlexClient objects connected to server.

client(name)[source]

Returns the PlexClient that matches the specified name.

Parameters:: name (str) – Name of the client to return.
Raises:: NotFound – Unknown client name.

createCollection(title, section, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs)[source]

Creates and returns a new Collection.

Parameters:

title (str) – Title of the collection.
section (LibrarySection, str) – The library section to create the collection in.
items (List) – Regular collections only, list of Audio, Video, or Photo objects to be added to the collection.
smart (bool) – True to create a smart collection. Default False.
limit (int) – Smart collections only, limit the number of items in the collection.
libtype (str) – Smart collections only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).
sort (str or list, optional) – Smart collections only, a string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – Smart collections only, a dictionary of advanced filters. See search() for more info.
**kwargs (dict) – Smart collections only, additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When no items are included to create the collection.
plexapi.exceptions.BadRequest – When mixing media types in the collection.

Returns:

A new instance of the created Collection.

Return type:

Collection

Example

# Create a regular collection
movies = plex.library.section("Movies")
movie1 = movies.get("Big Buck Bunny")
movie2 = movies.get("Sita Sings the Blues")
collection = plex.createCollection(
    title="Favorite Movies",
    section=movies,
    items=[movie1, movie2]
)

# Create a smart collection
collection = plex.createCollection(
    title="Recently Aired Comedy TV Shows",
    section="TV Shows",
    smart=True,
    sort="episode.originallyAvailableAt:desc",
    filters={"episode.originallyAvailableAt>>": "4w", "genre": "comedy"}
)

createPlaylist(title, section=None, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, m3ufilepath=None, **kwargs)[source]

Creates and returns a new Playlist.

Parameters:

title (str) – Title of the playlist.
section (LibrarySection, str) – Smart playlists and m3u import only, the library section to create the playlist in.
items (List) – Regular playlists only, list of Audio, Video, or Photo objects to be added to the playlist.
smart (bool) – True to create a smart playlist. Default False.
limit (int) – Smart playlists only, limit the number of items in the playlist.
libtype (str) – Smart playlists only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).
sort (str or list, optional) – Smart playlists only, a string of comma separated sort fields or a list of sort fields in the format column:dir. See search() for more info.
filters (dict) – Smart playlists only, a dictionary of advanced filters. See search() for more info.
m3ufilepath (str) – Music playlists only, the full file path to an m3u file to import. Note: This will overwrite any playlist previously created from the same m3u file.
**kwargs (dict) – Smart playlists only, additional custom filters to apply to the search results. See search() for more info.

Raises:

plexapi.exceptions.BadRequest – When no items are included to create the playlist.
plexapi.exceptions.BadRequest – When mixing media types in the playlist.
plexapi.exceptions.BadRequest – When attempting to import m3u file into non-music library.
plexapi.exceptions.BadRequest – When failed to import m3u file.

Returns:

A new instance of the created Playlist.

Return type:

Playlist

Example

# Create a regular playlist
episodes = plex.library.section("TV Shows").get("Game of Thrones").episodes()
playlist = plex.createPlaylist(
    title="GoT Episodes",
    items=episodes
)

# Create a smart playlist
playlist = plex.createPlaylist(
    title="Top 10 Unwatched Movies",
    section="Movies",
    smart=True,
    limit=10,
    sort="audienceRating:desc",
    filters={"audienceRating>>": 8.0, "unwatched": True}
)

# Create a music playlist from an m3u file
playlist = plex.createPlaylist(
    title="Favorite Tracks",
    section="Music",
    m3ufilepath="/path/to/playlist.m3u"
)

createPlayQueue(item, **kwargs)[source]

Creates and returns a new PlayQueue.

Parameters:

item (Media or Playlist) – Media or playlist to add to PlayQueue.
kwargs (dict) – See ~plexapi.playqueue.PlayQueue.create.

downloadDatabases(savepath=None, unpack=False, showstatus=False)[source]

Download databases.

Parameters:

savepath (str) – Defaults to current working dir.
unpack (bool) – Unpack the zip file.
showstatus (bool) – Display a progressbar.

downloadLogs(savepath=None, unpack=False, showstatus=False)[source]

Download server logs.

Parameters:

savepath (str) – Defaults to current working dir.
unpack (bool) – Unpack the zip file.
showstatus (bool) – Display a progressbar.

butlerTasks()[source]: Return a list of ButlerTask objects.

runButlerTask(task)[source]

Manually run a butler task immediately instead of waiting for the scheduled task to run. Note: The butler task is run asynchronously. Check Plex Web to monitor activity.

Parameters:: task (str) – The name of the task to run. (e.g. ‘BackupDatabase’)

Example

availableTasks = [task.name for task in plex.butlerTasks()]
print("Available butler tasks:", availableTasks)

checkForUpdate(force=True, download=False)[source]

Returns a Release object containing release info if an update is available or None if no update is available.

Parameters:

force (bool) – Force server to check for new releases
download (bool) – Download if a update is available.

isLatest()[source]: Returns True if the installed version of Plex Media Server is the latest.

canInstallUpdate()[source]: Returns True if the newest version of Plex Media Server can be installed automatically. (e.g. Windows and Mac can install updates automatically, but Docker and NAS devices cannot.)

installUpdate()[source]: Automatically install the newest version of Plex Media Server.

history(maxresults=None, mindate=None, ratingKey=None, accountID=None, librarySectionID=None)[source]

Returns a list of media items from watched history. If there are many results, they will be fetched from the server in batches of X_PLEX_CONTAINER_SIZE amounts. If you’re only looking for the first <num> results, it would be wise to set the maxresults option to that amount so this functions doesn’t iterate over all results on the server.

Parameters:

maxresults (int) – Only return the specified number of results (optional).
mindate (datetime) – Min datetime to return results from. This really helps speed up the result listing. For example: datetime.now() - timedelta(days=7)
ratingKey (int/str) –
accountID (int/str) –
librarySectionID (int/str) –

playlists(playlistType=None, sectionId=None, title=None, sort=None, **kwargs)[source]

Returns a list of all Playlist objects on the server.

Parameters:

playlistType (str, optional) – The type of playlists to return (audio, video, photo). Default returns all playlists.
sectionId (int, optional) – The section ID (key) of the library to search within.
title (str, optional) – General string query to search for. Partial string matches are allowed.
sort (str or list, optional) – A string of comma separated sort fields in the format column:dir.

playlist(title)[source]

Returns the Playlist that matches the specified title.

Parameters:: title (str) – Title of the playlist to return.
Raises:: NotFound – Unable to find playlist.

optimizedItems(removeAll=None)[source]: Returns list of all Optimized objects connected to server.

optimizedItem(optimizedID)[source]: Returns single queued optimized item Video object. Allows for using optimized item ID to connect back to source item.

conversions(pause=None)[source]: Returns list of all Conversion objects connected to server.

currentBackgroundProcess()[source]: Returns list of all TranscodeJob objects running or paused on server.

query(key, method=None, headers=None, params=None, timeout=None, **kwargs)[source]: Main method used to handle HTTPS requests to the Plex server. This method helps by encoding the response to utf-8 and parsing the returned XML into and ElementTree object. Returns None if no data exists in the response.

search(query, mediatype=None, limit=None, sectionId=None)[source]

Returns a list of media items or filter categories from the resulting Hub Search against all items in your Plex library. This searches genres, actors, directors, playlists, as well as all the obvious media titles. It performs spell-checking against your search terms (because KUROSAWA is hard to spell). It also provides contextual search results. So for example, if you search for ‘Pernice’, it’ll return ‘Pernice Brothers’ as the artist result, but we’ll also go ahead and return your most-listened to albums and tracks from the artist. If you type ‘Arnold’ you’ll get a result for the actor, but also the most recently added movies he’s in.

Parameters:

query (str) – Query to use when searching your library.
mediatype (str, optional) – Limit your search to the specified media type. actor, album, artist, autotag, collection, director, episode, game, genre, movie, photo, photoalbum, place, playlist, shared, show, tag, track
limit (int, optional) – Limit to the specified number of results per Hub.
sectionId (int, optional) – The section ID (key) of the library to search within.

continueWatching()[source]: Return a list of all items in the Continue Watching hub.

sessions()[source]: Returns a list of all active session (currently playing) media objects.

transcodeSessions()[source]: Returns a list of all active TranscodeSession objects.

startAlertListener(callback=None, callbackError=None)[source]

Creates a websocket connection to the Plex Server to optionally receive notifications. These often include messages from Plex about media scans as well as updates to currently running Transcode Sessions.

Returns a new AlertListener object.

Note: websocket-client must be installed in order to use this feature.

>> pip install websocket-client

Parameters:

callback (func) – Callback function to call on received messages.
callbackError (func) – Callback function to call on errors.

Raises:

Unsupported – Websocket-client not installed.

transcodeImage(imageUrl, height, width, opacity=None, saturation=None, blur=None, background=None, blendColor=None, minSize=True, upscale=True, imageFormat=None)[source]

Returns the URL for a transcoded image.

Parameters:

imageUrl (str) – The URL to the image (eg. returned by thumbUrl() or artUrl()). The URL can be an online image.
height (int) – Height to transcode the image to.
width (int) – Width to transcode the image to.
opacity (int, optional) – Change the opacity of the image (0 to 100)
saturation (int, optional) – Change the saturation of the image (0 to 100).
blur (int, optional) – The blur to apply to the image in pixels (e.g. 3).
background (str, optional) – The background hex colour to apply behind the opacity (e.g. ‘000000’).
blendColor (str, optional) – The hex colour to blend the image with (e.g. ‘000000’).
minSize (bool, optional) – Maintain smallest dimension. Default True.
upscale (bool, optional) – Upscale the image if required. Default True.
imageFormat (str, optional) – ‘jpeg’ (default) or ‘png’.

url(key, includeToken=None)[source]: Build a URL string with proper token argument. Token will be appended to the URL if either includeToken is True or CONFIG.log.show_secrets is ‘true’.

refreshSynclist()[source]: Force PMS to download new SyncList from Plex.tv.

refreshContent()[source]: Force PMS to refresh content for known SyncLists.

refreshSync()[source]: Calls refreshSynclist() and refreshContent(), just like the Plex Web UI does when you click ‘refresh’.

bandwidth(timespan=None, **kwargs)[source]

Returns a list of StatisticsBandwidth objects with the Plex server dashboard bandwidth data.

Parameters:

timespan (str, optional) – The timespan to bin the bandwidth data. Default is seconds. Available timespans: seconds, hours, days, weeks, months.
**kwargs (dict, optional) –
Any of the available filters that can be applied to the bandwidth data. The time frame (at) and bytes can also be filtered using less than or greater than (see examples below).
- accountID (int): The SystemAccount ID to filter.
- at (datetime): The time frame to filter (inclusive). The time frame can be either:
  1. An exact time frame (e.g. Only December 1st 2020 at=datetime(2020, 12, 1)).
  2. Before a specific time (e.g. Before and including December 2020 at<=datetime(2020, 12, 1)).
  3. After a specific time (e.g. After and including January 2021 at>=datetime(2021, 1, 1)).
- bytes (int): The amount of bytes to filter (inclusive). The bytes can be either:
  1. An exact number of bytes (not very useful) (e.g. bytes=1024**3).
  2. Less than or equal number of bytes (e.g. bytes<=1024**3).
  3. Greater than or equal number of bytes (e.g. bytes>=1024**3).
- deviceID (int): The SystemDevice ID to filter.
- lan (bool): True to only retrieve local bandwidth, False to only retrieve remote bandwidth.
  Default returns all local and remote bandwidth.

Raises:

BadRequest – When applying an invalid timespan or unknown filter.

Example

from plexapi.server import PlexServer
plex = PlexServer('http://localhost:32400', token='xxxxxxxxxxxxxxxxxxxx')

# Filter bandwidth data for December 2020 and later, and more than 1 GB used.
filters = {
    'at>': datetime(2020, 12, 1),
    'bytes>': 1024**3
}

# Retrieve bandwidth data in one day timespans.
bandwidthData = plex.bandwidth(timespan='days', **filters)

# Print out bandwidth usage for each account and device combination.
for bandwidth in sorted(bandwidthData, key=lambda x: x.at):
    account = bandwidth.account()
    device = bandwidth.device()
    gigabytes = round(bandwidth.bytes / 1024**3, 3)
    local = 'local' if bandwidth.lan else 'remote'
    date = bandwidth.at.strftime('%Y-%m-%d')
    print(f'{account.name} used {gigabytes} GB of {local} bandwidth on {date} from {device.name}')

resources()[source]: Returns a list of StatisticsResources objects with the Plex server dashboard resources data.

getWebURL(base=None, playlistTab=None)[source]

Returns the Plex Web URL for the server.

Parameters:

base (str) – The base URL before the fragment (#!). Default is https://app.plex.tv/desktop.
playlistTab (str) – The playlist tab (audio, video, photo). Only used for the playlist URL.

class plexapi.server.Account(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Contains the locally cached MyPlex account information. The properties provided don’t match the MyPlexAccount object very well. I believe this exists because access to myplex is not required to get basic plex information. I can’t imagine object is terribly useful except unless you were needed this information while offline.

Parameters:

server (PlexServer) – PlexServer this account is connected to (optional)
data (ElementTree) – Response from PlexServer used to build this object (optional).

Variables:

authToken (str) – Plex authentication token to access the server.
mappingError (str) – Unknown
mappingErrorMessage (str) – Unknown
mappingState (str) – Unknown
privateAddress (str) – Local IP address of the Plex server.
privatePort (str) – Local port of the Plex server.
publicAddress (str) – Public IP address of the Plex server.
publicPort (str) – Public port of the Plex server.
signInState (str) – Signin state for this account (ex: ok).
subscriptionActive (str) – True if the account subscription is active.
subscriptionFeatures (str) – List of features allowed by the server for this account. This may be based on your PlexPass subscription. Features include: camera_upload, cloudsync, content_filter, dvr, hardware_transcoding, home, lyrics, music_videos, pass, photo_autotags, premium_music_metadata, session_bandwidth_restrictions, sync, trailers, webhooks’ (and maybe more).
subscriptionState (str) – ‘Active’ if this subscription is active.
username (str) – Plex account username (user@example.com).

class plexapi.server.Activity(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

A currently running activity on the PlexServer.

class plexapi.server.Release(server, data, initpath=None, parent=None)[source]: Bases: PlexObject

class plexapi.server.SystemAccount(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single system account.

Variables:

TAG (str) – ‘Account’
autoSelectAudio (bool) – True or False if the account has automatic audio language enabled.
defaultAudioLanguage (str) – The default audio language code for the account.
defaultSubtitleLanguage (str) – The default subtitle language code for the account.
id (int) – The Plex account ID.
key (str) – API URL (/accounts/<id>)
name (str) – The username of the account.
subtitleMode (bool) – The subtitle mode for the account.
thumb (str) – URL for the account thumbnail.

class plexapi.server.SystemDevice(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single system device.

Variables:

TAG (str) – ‘Device’
clientIdentifier (str) – The unique identifier for the device.
createdAt (datetime) – Datetime the device was created.
id (int) – The ID of the device (not the same as MyPlexDevice ID).
key (str) – API URL (/devices/<id>)
name (str) – The name of the device.
platform (str) – OS the device is running (Linux, Windows, Chrome, etc.)

class plexapi.server.StatisticsBandwidth(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single statistics bandwidth data.

Variables:

TAG (str) – ‘StatisticsBandwidth’
accountID (int) – The associated SystemAccount ID.
at (datetime) – Datetime of the bandwidth data.
bytes (int) – The total number of bytes for the specified time span.
deviceID (int) – The associated SystemDevice ID.
lan (bool) – True or False whether the bandwidth is local or remote.
timespan (int) – The time span for the bandwidth data. 1: months, 2: weeks, 3: days, 4: hours, 6: seconds.

account()[source]: Returns the SystemAccount associated with the bandwidth data.

device()[source]: Returns the SystemDevice associated with the bandwidth data.

class plexapi.server.StatisticsResources(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single statistics resources data.

Variables:

TAG (str) – ‘StatisticsResources’
at (datetime) – Datetime of the resource data.
hostCpuUtilization (float) – The system CPU usage %.
hostMemoryUtilization (float) – The Plex Media Server CPU usage %.
processCpuUtilization (float) – The system RAM usage %.
processMemoryUtilization (float) – The Plex Media Server RAM usage %.
timespan (int) – The time span for the resource data (6: seconds).

class plexapi.server.ButlerTask(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single scheduled butler task.

Variables:

TAG (str) – ‘ButlerTask’
description (str) – The description of the task.
enabled (bool) – Whether the task is enabled.
interval (int) – The interval the task is run in days.
name (str) – The name of the task.
scheduleRandomized (bool) – Whether the task schedule is randomized.
title (str) – The title of the task.

class plexapi.server.Identity(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a server identity.

Variables:

claimed (bool) – True or False if the server is claimed.
machineIdentifier (str) – The Plex server machine identifier.
version (str) – The Plex server version.

Settings plexapi.settings

class plexapi.settings.Settings(server, data, initpath=None)[source]

Bases: PlexObject

Container class for all settings. Allows getting and setting PlexServer settings.

Variables:: key (str) – ‘/:/prefs’

all()[source]: Returns a list of all Setting objects available.

get(id)[source]: Return the Setting object with the specified id.

groups()[source]: Returns a dict of lists for all Setting objects grouped by setting group.

group(group)[source]

Return a list of all Setting objects in the specified group.

Parameters:: group (str) – Group to return all settings.

save()[source]: Save any outstanding setting changes to the PlexServer. This performs a full reload() of Settings after complete.

class plexapi.settings.Setting(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a single Plex setting.

Variables:

id (str) – Setting id (or name).
label (str) – Short description of what this setting is.
summary (str) – Long description of what this setting is.
type (str) – Setting type (text, int, double, bool).
default (str) – Default value for this setting.
value (str,bool,int,float) – Current value for this setting.
hidden (bool) – True if this is a hidden setting.
advanced (bool) – True if this is an advanced setting.
group (str) – Group name this setting is categorized as.
enumValues (list,dict) – List or dictionary of valid values for this setting.

set(value)[source]: Set a new value for this setting. NOTE: You must call plex.settings.save() for before any changes to setting values are persisted to the PlexServer.

toUrl()[source]: Helper for urls

class plexapi.settings.Preferences(server, data, initpath=None, parent=None)[source]

Bases: Setting

Represents a single Preferences.

Variables:

TAG (str) – ‘Setting’
FILTER (str) – ‘preferences’

General Settings

butlerUpdateChannel (text): Update Channel. (default: 16; choices: 16:Public|8:Plex Pass)
collectUsageData (bool): Send anonymous usage data to Plex. This helps us improve your experience (for example, to help us match movies and TV shows). (default: True)
friendlyName (text): Friendly name. This name will be used to identify this media server to other computers on your network. If you leave it blank, your computer’s name will be used instead.
logDebug (bool): Enable Plex Media Server debug logging. (default: True)
logTokens (bool): Allow Plex Media Server tokens in logs. Media server tokens can be used to gain access to library content. Don’t share logs containing tokens publicly. A server restart is required for a change to take effect.
logVerbose (bool): Enable Plex Media Server verbose logging.

Scheduled Task Settings

butlerDatabaseBackupPath (text): Backup directory. The directory in which database backups are stored. (default: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases)
butlerEndHour (int): Time at which tasks stop running. The time at which the background maintenance tasks stop running. (default: 5; choices: 0:Midnight|1:1 am|2:2 am|3:3 am|4:4 am|5:5 am|6:6 am|7:7 am|8:8 am|9:9 am|10:10 am|11:11 am|12:Noon|13:1 pm|14:2 pm|15:3 pm|16:4 pm|17:5 pm|18:6 pm|19:7 pm|20:8 pm|21:9 pm|22:10 pm|23:11 pm)
butlerStartHour (int): Time at which tasks start to run. The time at which the server starts running background maintenance tasks. (default: 2; choices: 0:Midnight|1:1 am|2:2 am|3:3 am|4:4 am|5:5 am|6:6 am|7:7 am|8:8 am|9:9 am|10:10 am|11:11 am|12:Noon|13:1 pm|14:2 pm|15:3 pm|16:4 pm|17:5 pm|18:6 pm|19:7 pm|20:8 pm|21:9 pm|22:10 pm|23:11 pm)
butlerTaskBackupDatabase (bool): Backup database every three days. (default: True)
butlerTaskCleanOldBundles (bool): Remove old bundles every week. (default: True)
butlerTaskCleanOldCacheFiles (bool): Remove old cache files every week. (default: True)
butlerTaskDeepMediaAnalysis (bool): Perform extensive media analysis during maintenance. (default: True)
butlerTaskOptimizeDatabase (bool): Optimize database every week. (default: True)
butlerTaskRefreshEpgGuides (bool): Perform refresh of program guide data.. (default: True)
butlerTaskRefreshLibraries (bool): Update all libraries during maintenance.
butlerTaskRefreshLocalMedia (bool): Refresh local metadata every three days. (default: True)
butlerTaskRefreshPeriodicMetadata (bool): Refresh metadata periodically. (default: True)
butlerTaskUpgradeMediaAnalysis (bool): Upgrade media analysis during maintenance. (default: True)

Channels Settings

disableCapabilityChecking (bool): Disable capability checking. Capability checking ensures that plug-ins that are incompatible with this version of the server or the current client application you are using are hidden. Disabling capability checking is useful during development, but will enable access to plug-ins that may perform unreliably with certain client applications.
iTunesLibraryXmlPath (text): iTunes library XML path.
iTunesSharingEnabled (bool): Enable iTunes channel. A server restart is required for a change to take effect.
pluginsLaunchTimeout (int): Number of seconds to wait before a plugin times out. (default: 180)

DLNA Settings

dlnaAnnouncementLeaseTime (int): DLNA server announcement lease time. Duration in seconds of DLNA Server SSDP announcement lease time. (default: 1800)
dlnaClientPreferences (text): DLNA client preferences. Client-specific configuration settings for the DLNA server.
dlnaDefaultProtocolInfo (text): DLNA default protocol info. Protocol info string used in GetProtocolInfo responses by the DLNA server. (default: http-get::video/mpeg:,http-get::video/mp4:,http-get::video/vnd.dlna.mpeg-tts:,http-get::video/avi:,http-get::video/x-matroska:,http-get::video/x-ms-wmv:,http-get::video/wtv:,http-get::audio/mpeg:,http-get::audio/mp3:,http-get::audio/mp4:,http-get::audio/x-ms-wma,http-get::audio/wav:,http-get::audio/L16:,http-get:image/jpeg:,http-get:image/png:,http-get:image/gif:,http-get:image/tiff:)
dlnaDescriptionIcons (text): DLNA server description icons. Icons offered by DLNA server when devices request server description. (default: png,jpeg;260x260,120x120,48x48)
dlnaDeviceDiscoveryInterval (int): DLNA media renderer discovery interval. Number of seconds between DLNA media renderer discovery requests. (default: 60)
dlnaEnabled (bool): Enable the DLNA server. This allows the server to stream media to DLNA (Digital Living Network Alliance) devices. (default: True)
dlnaPlatinumLoggingLevel (text): DLNA server logging level. (default: OFF; choices: OFF|FATAL|SEVERE|WARNING|INFO|FINE|FINER|FINEST|ALL)
dlnaReportTimeline (bool): DLNA server timeline reporting. Enable the DLNA server to report timelines for video play activity. (default: True)

Extras Settings

cinemaTrailersFromBluRay (bool): Include Cinema Trailers from new and upcoming movies on Blu-ray. This feature is Plex Pass only.
cinemaTrailersFromLibrary (bool): Include Cinema Trailers from movies in my library. (default: True)
cinemaTrailersFromTheater (bool): Include Cinema Trailers from new and upcoming movies in theaters. This feature is Plex Pass only.
cinemaTrailersPrerollID (text): Cinema Trailers pre-roll video. Copy and paste the video’s detail page URL into this field.
cinemaTrailersType (int): Choose Cinema Trailers from. (default: 1; choices: 0:All movies|1:Only unwatched movies)

Library Settings

allowMediaDeletion (bool): Allow media deletion. The owner of the server will be allowed to delete media files from disk. (default: True)
autoEmptyTrash (bool): Empty trash automatically after every scan. (default: True)
fSEventLibraryPartialScanEnabled (bool): Run a partial scan when changes are detected. When changes to library folders are detected, only scan the folder that changed.
fSEventLibraryUpdatesEnabled (bool): Update my library automatically. Your library will be updated automatically when changes to library folders are detected.
generateBIFBehavior (text): Generate video preview thumbnails. Video preview thumbnails provide live updates in Now Playing and while seeking on supported apps. Thumbnail generation may take a long time, cause high CPU usage, and consume additional disk space. You can turn off thumbnail generation for individual libraries in the library’s advanced settings. (default: never; choices: never:never|scheduled:as a scheduled task|asap:as a scheduled task and when media is added)
generateChapterThumbBehavior (text): Generate chapter thumbnails. Chapter thumbnails provide images in the chapter view on supported apps. They can take a long time to generate and consume additional disk space. (default: scheduled; choices: never:never|scheduled:as a scheduled task|asap:as a scheduled task and when media is added)
onDeckWindow (int): Weeks to consider for On Deck. Shows that have not been watched in this many weeks will not appear in On Deck. (default: 16)
scannerLowPriority (bool): Run scanner tasks at a lower priority.
scheduledLibraryUpdateInterval (int): Library update interval. (default: 3600; choices: 900:every 15 minutes|1800:every 30 minutes|3600:hourly|7200:every 2 hours|21600:every 6 hours|43200:every 12 hours|86400:daily)
scheduledLibraryUpdatesEnabled (bool): Update my library periodically.
watchMusicSections (bool): Include music libraries in automatic updates. Linux systems limit the maximum number of watched directories; this may cause problems with large music libraries.

Network Settings

allowedNetworks (text): List of IP addresses and networks that are allowed without auth. Comma separated list of IP addresses or IP/netmask entries for networks that are allowed to access Plex Media Server without logging in. When the server is signed out and this value is set, only localhost and addresses on this list will be allowed.
configurationUrl (text): Web Manager URL. (default: http://127.0.0.1:32400/web)
customCertificateDomain (text): Custom certificate domain. Domain name to be published to plex.tv using your mapped port; must match a name from the custom certificate file.
customCertificateKey (text): Custom certificate encryption key.
customCertificatePath (text): Custom certificate location. Path to a PKCS #12 file containing a certificate and private key to enable TLS support on a custom domain.
customConnections (text): Custom server access URLs. A comma-separated list of URLs (http or https) which are published up to plex.tv for server discovery.
enableHttpPipelining (bool): Enable HTTP Pipelining. This feature can enable higher performance in the HTTP server component. A server restart is required for a change to take effect. (default: True)
enableIPv6 (bool): Enable server support for IPv6.
gdmEnabled (bool): Enable local network discovery (GDM). This enables the media server to discover other servers and players on the local network. (default: True)
lanNetworksBandwidth (text): LAN Networks. Comma separated list of IP addresses or IP/netmask entries for networks that will be considered to be on the local network when enforcing bandwidth restrictions. If set, all other IP addresses will be considered to be on the external network and and will be subject to external network bandwidth restrictions. If left blank, only the server’s subnet is considered to be on the local network.
secureConnections (int): Secure connections. When set to “Required”, some unencrypted connections (originating from the Media Server computer) will still be allowed and apps that don’t support secure connections will not be able to connect at all. (default: 1; choices: 0:Required|1:Preferred|2:Disabled)
wanPerUserStreamCount (int): Remote streams allowed per user. Maximum number of simultaneous streams each user is allowed when not on the local network. (choices: 0:Unlimited|1:1|2:2|3:3|4:4|5:5|6:6|7:7|8:8|9:9|10:10|11:11|12:12|13:13|14:14|15:15|16:16|17:17|18:18|19:19|20:20)
webHooksEnabled (bool): Webhooks. This feature enables your server to send events to external services. (default: True)

Transcoder Settings

hardwareAcceleratedCodecs (bool): Use hardware acceleration when available (Experimental). Plex Media Server will attempt to use hardware-accelerated video codecs when encoding and decoding video. Hardware acceleration can make transcoding faster and allow more simultaneous video transcodes, but it can also reduce video quality and compatibility.
segmentedTranscoderTimeout (int): Segmented transcoder timeout. Timeout in seconds segmented transcodes wait for the transcoder to begin writing data. (default: 20)
transcodeCountLimit (int): Maximum simultaneous video transcode. Limit the number of simultaneous video transcode streams your server can utilize (choices: 0:Unlimited|1:1|2:2|3:3|4:4|5:5|6:6|7:7|8:8|9:9|10:10|11:11|12:12|13:13|14:14|15:15|16:16|17:17|18:18|19:19|20:20)
transcoderDefaultDuration (int): Transcoder default duration. Duration in minutes to use when transcoding something with an unknown duration. (default: 120)
transcoderH264BackgroundPreset (text): Background transcoding x264 preset. The x264 preset value used for background transcoding (Sync and Media Optimizer). Slower values will result in better video quality and smaller file sizes, but will take significantly longer to complete processing. (default: veryfast; choices: ultrafast:Ultra fast|superfast:Super fast|veryfast:Very fast|faster:Faster|fast:Fast|medium:Medium|slow:Slow|slower:Slower|veryslow:Very slow)
transcoderPruneBuffer (int): Transcoder default prune buffer. Amount in past seconds to retain before pruning segments from a transcode. (default: 300)
transcoderQuality (int): Transcoder quality. Quality profile used by the transcoder. (choices: 0:Automatic|1:Prefer higher speed encoding|2:Prefer higher quality encoding|3:Make my CPU hurt)
transcoderTempDirectory (text): Transcoder temporary directory. Directory to use when transcoding for temporary files.
transcoderThrottleBuffer (int): Transcoder default throttle buffer. Amount in seconds to buffer before throttling the transcoder. (default: 60)

Misc Settings

acceptedEULA (bool): Has the user accepted the EULA.
articleStrings (text): Comma-separated list of strings considered articles when sorting titles. A server restart is required for a change to take effect.. (default: the,das,der,a,an,el,la)
languageInCloud (bool): Use language preferences from plex.tv.
machineIdentifier (text): A unique identifier for the machine.
publishServerOnPlexOnlineKey (bool): Publish server on Plex Online. Publishing a server makes it automatically available on your client devices without any configuration of your router.
transcoderCanOnlyRemuxVideo (bool): The transcoder can only remux video.
transcoderVideoResolutionLimit (text): Maximum video output resolution for the transcoder. (default: 0x0)
wanPerStreamMaxUploadRate (int): Limit remote stream bitrate. Set the maximum bitrate of a remote stream from this server. (choices: 0:Original (No limit)|20000:20 Mbps (1080p)|12000:12 Mbps (1080p)|10000:10 Mbps (1080p)|8000:8 Mbps (1080p)|4000:4 Mbps (720p)|3000:3 Mbps (720p)|2000:2 Mbps (480p)|1500:1.5 Mbps (480p)|720:720 kbps|320:320 kbps)
wanTotalMaxUploadRate (int): External network total upload limit (kbps). Speed at which to limit the total bandwidth not on the local network in kilobits per second. Use 0 to set no limit.

Undocumented Settings

aBRKeepOldTranscodes (bool)
allowHighOutputBitrates (bool)
backgroundQueueIdlePaused (bool)
butlerTaskGarbageCollectBlobs (bool)
butlerTaskGenerateMediaIndexFiles (bool)
certificateVersion (int): default: 2
dvrShowUnsupportedDevices (bool)
enableABRDebugOverlay (bool)
enableAirplay (bool)
eyeQUser (text)
forceAutoAdjustQuality (bool)
generateIndexFilesDuringAnalysis (bool)
gracenoteUser (text)
hardwareDevicePath (text): default: /dev/dri/renderD128
lastAutomaticMappedPort (int)
manualPortMappingMode (bool)
manualPortMappingPort (int): default: 32400
minimumProgressTime (int): default: 60000
plexMetricsUrl (text): default: https://metrics.plex.tv
plexOnlineMail (text)
plexOnlineUrl (text): default: https://plex.tv
syncMyPlexLoginGCDeferral (int): default: 14400
syncPagingItemsLimit (int): default: 100
systemAudioCodecs (bool): default: True
transcoderH264MinimumCRF (double): default: 16.0
transcoderH264Options (text)
transcoderH264OptionsOverride (text)
transcoderH264Preset (text): default: veryfast
transcoderLivePruneBuffer (int): default: 5400
transcoderLogLevel (text): default: error

Sonos plexapi.sonos

class plexapi.sonos.PlexSonosClient(account, data)[source]

Bases: PlexClient

Class for interacting with a Sonos speaker via the Plex API. This class makes requests to an external Plex API which then forwards the Sonos-specific commands back to your Plex server & Sonos speakers. Use of this feature requires an active Plex Pass subscription and Sonos speakers linked to your Plex account. It also requires remote access to be working properly.

More details on the Sonos integration are available here: https://support.plex.tv/articles/218237558-requirements-for-using-plex-for-sonos/

The Sonos API emulates the Plex player control API closely: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API

Parameters:

account (PlexAccount) – PlexAccount instance this Sonos speaker is associated with.
data (ElementTree) – Response from Plex Sonos API used to build this client.

Variables:

deviceClass (str) – “speaker”
lanIP (str) – Local IP address of speaker.
machineIdentifier (str) – Unique ID for this device.
platform (str) – “Sonos”
platformVersion (str) – Build version of Sonos speaker firmware.
product (str) – “Sonos”
protocol (str) – “plex”
protocolCapabilities (list<str>) – List of client capabilities (timeline, playback, playqueues, provider-playback)
server (PlexServer) – Server this client is connected to.
session (Session) – Session object used for connection.
title (str) – Name of this Sonos speaker.
token (str) – X-Plex-Token used for authentication
_baseurl (str) – Address of public Plex Sonos API endpoint.
_commandId (int) – Counter for commands sent to Plex API.
_token (str) – Token associated with linked Plex account.
_session (obj) – Requests session object used to access this client.

playMedia(media, offset=0, **params)[source]

Start playback of the specified media item. See also:

Parameters:

media (Media) – Media item to be played back (movie, music, photo, playlist, playqueue).
offset (int) – Number of milliseconds at which to start playing with zero representing the beginning (default 0).
**params (dict) – Optional additional parameters to include in the playback request. See also: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API#modified-commands

Sync plexapi.sync

You can work with Mobile Sync on other devices straight away, but if you’d like to use your app as a sync-target (when you can set items to be synced to your app) you need to init some variables.

def init_sync():
    import plexapi
    plexapi.X_PLEX_PROVIDES = 'sync-target'
    plexapi.BASE_HEADERS['X-Plex-Sync-Version'] = '2'
    plexapi.BASE_HEADERS['X-Plex-Provides'] = plexapi.X_PLEX_PROVIDES

    # mimic iPhone SE
    plexapi.X_PLEX_PLATFORM = 'iOS'
    plexapi.X_PLEX_PLATFORM_VERSION = '11.4.1'
    plexapi.X_PLEX_DEVICE = 'iPhone'

    plexapi.BASE_HEADERS['X-Plex-Platform'] = plexapi.X_PLEX_PLATFORM
    plexapi.BASE_HEADERS['X-Plex-Platform-Version'] = plexapi.X_PLEX_PLATFORM_VERSION
    plexapi.BASE_HEADERS['X-Plex-Device'] = plexapi.X_PLEX_DEVICE

You have to fake platform/device/model because transcoding profiles are hardcoded in Plex, and you obviously have to explicitly specify that your app supports sync-target.

class plexapi.sync.SyncItem(server, data, initpath=None, clientIdentifier=None)[source]

Bases: PlexObject

Represents single sync item, for specified server and client. When you saying in the UI to sync “this” to “that” you’re basically creating a sync item.

Variables:

id (int) – unique id of the item.
clientIdentifier (str) – an identifier of Plex Client device, to which the item is belongs.
machineIdentifier (str) – the id of server which holds all this content.
version (int) – current version of the item. Each time you modify the item (e.g. by changing amount if media to sync) the new version is created.
rootTitle (str) –
the title of library/media from which the sync item was created. E.g.:
- when you create an item for an episode 3 of season 3 of show Example, the value would be Title of Episode 3
- when you create an item for a season 3 of show Example, the value would be Season 3
- when you set to sync all your movies in library named “My Movies” to value would be My Movies.
title (str) – the title which you’ve set when created the sync item.
metadataType (str) – the type of media which hides inside, can be episode, movie, etc.
contentType (str) – basic type of the content: video or audio.
status (Status) – current status of the sync.
mediaSettings (MediaSettings) – media transcoding settings used for the item.
policy (Policy) – the policy of which media to sync.
location (str) – plex-style library url with all required filters / sorting.

server()[source]: Returns MyPlexResource with server of current item.

getMedia()[source]: Returns list of Playable which belong to this sync item.

markDownloaded(media)[source]

Mark the file as downloaded (by the nature of Plex it will be marked as downloaded within any SyncItem where it presented).

Parameters:: media (base.Playable) – the media to be marked as downloaded.

delete()[source]: Removes current SyncItem

class plexapi.sync.SyncList(server, data, initpath=None, parent=None)[source]

Bases: PlexObject

Represents a Mobile Sync state, specific for single client, within one SyncList may be presented items from different servers.

Variables:

clientId (str) – an identifier of the client.
items (List<SyncItem>) – list of registered items to sync.

class plexapi.sync.Status(itemsCount, itemsCompleteCount, state, totalSize, itemsDownloadedCount, itemsReadyCount, itemsSuccessfulCount, failureCode, failure)[source]

Bases: object

Represents a current status of specific SyncItem.

Variables:

failureCode – unknown, never got one yet.
failure – unknown.
state (str) – server-side status of the item, can be completed, pending, empty, and probably something else.
itemsCount (int) – total items count.
itemsCompleteCount (int) – count of transcoded and/or downloaded items.
itemsDownloadedCount (int) – count of downloaded items.
itemsReadyCount (int) – count of transcoded items, which can be downloaded.
totalSize (int) – total size in bytes of complete items.
itemsSuccessfulCount (int) – unknown, in my experience it always was equal to itemsCompleteCount.

class plexapi.sync.MediaSettings(maxVideoBitrate=4000, videoQuality=100, videoResolution='1280x720', audioBoost=100, musicBitrate=192, photoQuality=74, photoResolution='1920x1080', subtitleSize=100)[source]

Bases: object

Transcoding settings used for all media within SyncItem.

Variables:

audioBoost (int) – unknown.
maxVideoBitrate (int|str) – maximum bitrate for video, may be empty string.
musicBitrate (int|str) – maximum bitrate for music, may be an empty string.
photoQuality (int) – photo quality on scale 0 to 100.
photoResolution (str) – maximum photo resolution, formatted as WxH (e.g. 1920x1080).
videoResolution (str) – maximum video resolution, formatted as WxH (e.g. 1280x720, may be empty).
subtitleSize (int) – subtitle size on scale 0 to 100.
videoQuality (int) – video quality on scale 0 to 100.

static createVideo(videoQuality)[source]

Returns a MediaSettings object, based on provided video quality value.

Parameters:: videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in this module.
Raises:: BadRequest – When provided unknown video quality.

static createMusic(bitrate)[source]

Returns a MediaSettings object, based on provided music quality value

Parameters:: bitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module

static createPhoto(resolution)[source]

Returns a MediaSettings object, based on provided photo quality value.

Parameters:: resolution (str) – maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module.
Raises:: BadRequest – When provided unknown video quality.

class plexapi.sync.Policy(scope, unwatched, value=0)[source]

Bases: object

Policy of syncing the media (how many items to sync and process watched media or not).

Variables:

scope (str) – type of limitation policy, can be count or all.
value (int) – amount of media to sync, valid only when scope=count.
unwatched (bool) – True means disallow to sync watched media.

static create(limit=None, unwatched=False)[source]

Creates a Policy object for provided options and automatically sets proper scope value.

Parameters:

limit (int) – limit items by count.
unwatched (bool) – if True then watched items wouldn’t be synced.

Returns:

Policy.

Utils plexapi.utils

class plexapi.utils.SecretsFilter(secrets=None)[source]

Bases: Filter

Logging filter to hide secrets.

filter(record)[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

plexapi.utils.registerPlexObject(cls)[source]: Registry of library types we may come across when parsing XML. This allows us to define a few helper functions to dynamically convert the XML into objects. See buildItem() below for an example.

plexapi.utils.getPlexObject(ehash, default)[source]: Return the PlexObject class for the specified ehash. This recursively looks up the class with the highest specificity, falling back to the default class if not found.

plexapi.utils.cast(func, value)[source]

Cast the specified value to the specified type (returned by func). Currently this only support str, int, float, bool. Should be extended if needed.

Parameters:

func (func) – Callback function to used cast to type (int, bool, float).
value (any) – value to be cast and returned.

plexapi.utils.joinArgs(args)[source]

Returns a query string (uses for HTTP URLs) where only the value is URL encoded. Example return value: ‘?genre=action&type=1337’.

Parameters:: args (dict) – Arguments to include in query string.

plexapi.utils.rget(obj, attrstr, default=None, delim='.')[source]

Returns the value at the specified attrstr location within a nested tree of dicts, lists, tuples, functions, classes, etc. The lookup is done recursively for each key in attrstr (split by by the delimiter) This function is heavily influenced by the lookups used in Django templates.

Parameters:

obj (any) – Object to start the lookup in (dict, obj, list, tuple, etc).
attrstr (str) – String to lookup (ex: ‘foo.bar.baz.value’)
default (any) – Default value to return if not found.
delim (str) – Delimiter separating keys in attrstr.

plexapi.utils.searchType(libtype)[source]

Returns the integer value of the library string type.

Parameters:: libtype (str) – LibType to lookup (See SEARCHTYPES)
Raises:: NotFound – Unknown libtype

plexapi.utils.reverseSearchType(libtype)[source]

Returns the string value of the library type.

Parameters:: libtype (int) – Integer value of the library type.
Raises:: NotFound – Unknown libtype

plexapi.utils.tagType(tag)[source]

Returns the integer value of the library tag type.

Parameters:: tag (str) – Tag to lookup (See TAGTYPES)
Raises:: NotFound – Unknown tag

plexapi.utils.reverseTagType(tag)[source]

Returns the string value of the library tag type.

Parameters:: tag (int) – Integer value of the library tag type.
Raises:: NotFound – Unknown tag

plexapi.utils.threaded(callback, listargs)[source]

Returns the result of <callback> for each set of *args in listargs. Each call to <callback> is called concurrently in their own separate threads.

Parameters:

callback (func) – Callback function to apply to each set of *args.
listargs (list) – List of lists; *args to pass each thread.

plexapi.utils.toDatetime(value, format=None)[source]

Returns a datetime object from the specified value.

Parameters:

value (str) – value to return as a datetime
format (str) – Format to pass strftime (optional; if value is a str).

plexapi.utils.millisecondToHumanstr(milliseconds)[source]

Returns human readable time duration [D day[s], ]HH:MM:SS.UUU from milliseconds.

Parameters:: milliseconds (str, int) – time duration in milliseconds.

plexapi.utils.toList(value, itemcast=None, delim=',')[source]

Returns a list of strings from the specified value.

Parameters:

value (str) – comma delimited string to convert to list.
itemcast (func) – Function to cast each list item to (default str).
delim (str) – string delimiter (optional; default ‘,’).

plexapi.utils.downloadSessionImages(server, filename=None, height=150, width=150, opacity=100, saturation=100)[source]

Helper to download a bif image or thumb.url from plex.server.sessions.

Parameters:

filename (str) – default to None,
height (int) – Height of the image.
width (int) – width of the image.
opacity (int) – Opacity of the resulting image (possibly deprecated).
saturation (int) – Saturating of the resulting image.

Returns:

{‘filepath’: ‘<filepath>’, ‘url’: ‘http://<url>’}, {‘<username>’: {filepath, url}}, …

Return type:

{‘hellowlol’

plexapi.utils.download(url, token, filename=None, savepath=None, session=None, chunksize=4096, unpack=False, mocked=False, showstatus=False)[source]

Helper to download a thumb, videofile or other media item. Returns the local: path to the downloaded file.

Parameters:

url (str) – URL where the content be reached.
token (str) – Plex auth token to include in headers.
filename (str) – Filename of the downloaded file, default None.
savepath (str) – Defaults to current working dir.
chunksize (int) – What chunksize read/write at the time.
mocked (bool) – Helper to do everything except write the file.
unpack (bool) – Unpack the zip file.
showstatus – Display a progressbar.

plexapi.utils.getMyPlexAccount(opts=None)[source]: Helper function tries to get a MyPlex Account instance by checking the the following locations for a username and password. This is useful to create user-friendly command line tools. 1. command-line options (opts). 2. environment variables and config.ini 3. Prompt on the command line.

plexapi.utils.createMyPlexDevice(headers, account, timeout=10)[source]

Helper function to create a new MyPlexDevice. Returns a new MyPlexDevice instance.

Parameters:

headers (dict) – Provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required.
account (MyPlexAccount) – The Plex account to create the device on.
timeout (int) – Timeout in seconds to wait for device login.

plexapi.utils.plexOAuth(headers, forwardUrl=None, timeout=120)[source]

Helper function for Plex OAuth login. Returns a new MyPlexAccount instance.

Parameters:

headers (dict) – Provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required.
forwardUrl (str, optional) – The url to redirect the client to after login.
timeout (int, optional) – Timeout in seconds to wait for device login. Default 120 seconds.

plexapi.utils.choose(msg, items, attr)[source]: Command line helper to display a list of choices, asking the user to choose one of the options.

plexapi.utils.getAgentIdentifier(section, agent)[source]: Return the full agent identifier from a short identifier, name, or confirm full identifier.

plexapi.utils.iterXMLBFS(root, tag=None)[source]: Iterate through an XML tree using a breadth-first search. If tag is specified, only return nodes with that tag.

plexapi.utils.toJson(obj, **kwargs)[source]

Convert an object to a JSON string.

Parameters:

obj (object) – The object to convert.
**kwargs (dict) – Keyword arguments to pass to json.dumps().

plexapi.utils.sha1hash(guid)[source]: Return the SHA1 hash of a guid.

Video plexapi.video

class plexapi.video.Video(server, data, initpath=None, parent=None)[source]

Bases: PlexPartialObject, PlayedUnplayedMixin

Base class for all video objects including Movie, Show, Season, Episode, and Clip.

Variables:

addedAt (datetime) – Datetime the item was added to the library.
art (str) – URL to artwork image (/library/metadata/<ratingKey>/art/<artid>).
artBlurHash (str) – BlurHash string for artwork image.
fields (List<Field>) – List of field objects.
guid (str) – Plex GUID for the movie, show, season, episode, or clip (plex://movie/5d776b59ad5437001f79c6f8).
key (str) – API URL (/library/metadata/<ratingkey>).
lastRatedAt (datetime) – Datetime the item was last rated.
lastViewedAt (datetime) – Datetime the item was last played.
librarySectionID (int) – LibrarySection ID.
librarySectionKey (str) – LibrarySection key.
librarySectionTitle (str) – LibrarySection title.
listType (str) – Hardcoded as ‘video’ (useful for search filters).
ratingKey (int) – Unique key identifying the item.
summary (str) – Summary of the movie, show, season, episode, or clip.
thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
thumbBlurHash (str) – BlurHash string for thumbnail image.
title (str) – Name of the movie, show, season, episode, or clip.
titleSort (str) – Title to use when sorting (defaults to title).
type (str) – ‘movie’, ‘show’, ‘season’, ‘episode’, or ‘clip’.
updatedAt (datetime) – Datetime the item was updated.
userRating (float) – Rating of the item (0.0 - 10.0) equaling (0 stars - 5 stars).
viewCount (int) – Count of times the item was played.

url(part)[source]: Returns the full url for something. Typically used for getting a specific image.

augmentation()[source]: Returns a list of Hub objects. Augmentation returns hub items relating to online media sources such as Tidal Music “Track from {item}” or “Soundtrack of {item}”. Plex Pass and linked Tidal account are required.

uploadSubtitles(filepath)[source]

Upload a subtitle file for the video.

Parameters:: filepath (str) – Path to subtitle file.

searchSubtitles(language='en', hearingImpaired=0, forced=0)[source]

Search for on-demand subtitles for the video. See https://support.plex.tv/articles/subtitle-search/.

Parameters:

language (str, optional) – Language code (ISO 639-1) of the subtitles to search for. Default ‘en’.
hearingImpaired (int, optional) – Search option for SDH subtitles. Default 0. (0 = Prefer non-SDH subtitles, 1 = Prefer SDH subtitles, 2 = Only show SDH subtitles, 3 = Only show non-SDH subtitles)
forced (int, optional) – Search option for forced subtitles. Default 0. (0 = Prefer non-forced subtitles, 1 = Prefer forced subtitles, 2 = Only show forced subtitles, 3 = Only show non-forced subtitles)

Returns:

List of SubtitleStream objects.

Return type:

List<SubtitleStream>

downloadSubtitles(subtitleStream)[source]

Download on-demand subtitles for the video. See https://support.plex.tv/articles/subtitle-search/.

Note: This method is asynchronous and returns immediately before subtitles are fully downloaded.

Parameters:: subtitleStream (SubtitleStream) – Subtitle object returned from searchSubtitles().

removeSubtitles(subtitleStream=None, streamID=None, streamTitle=None)[source]

Remove an upload or downloaded subtitle from the video.

Note: If the subtitle file is located inside video directory it will be deleted. Files outside of video directory are not affected. Embedded subtitles cannot be removed.

Parameters:

subtitleStream (SubtitleStream, optional) – Subtitle object to remove.
streamID (int, optional) – ID of the subtitle stream to remove.
streamTitle (str, optional) – Title of the subtitle stream to remove.

optimize(title='', target='', deviceProfile='', videoQuality=None, locationID=-1, limit=None, unwatched=False)[source]

Create an optimized version of the video.

Parameters:

title (str, optional) – Title of the optimized video.
target (str, optional) – Target quality profile: “Optimized for Mobile” (“mobile”), “Optimized for TV” (“tv”), “Original Quality” (“original”), or custom quality profile name (default “Custom: {deviceProfile}”).
deviceProfile (str, optional) – Custom quality device profile: “Android”, “iOS”, “Universal Mobile”, “Universal TV”, “Windows Phone”, “Windows”, “Xbox One”. Required if target is custom.
videoQuality (int, optional) – Index of the quality profile, one of VIDEO_QUALITY_* values defined in the sync module. Only used if target is custom.
locationID (int or Location, optional) – Default -1 for “In folder with original items”, otherwise a Location object or ID. See examples below.
limit (int, optional) – Maximum count of items to optimize, unlimited if None.
unwatched (bool, optional) – True to only optimized unwatched videos.

Raises:

BadRequest – Unknown quality profile target or missing deviceProfile and videoQuality.
BadRequest – Unknown location ID.

Example

# Optimize for mobile using defaults
video.optimize(target="mobile")

# Optimize for Android at 10 Mbps 1080p
from plexapi.sync import VIDEO_QUALITY_10_MBPS_1080p
video.optimize(deviceProfile="Android", videoQuality=sync.VIDEO_QUALITY_10_MBPS_1080p)

# Optimize for iOS at original quality in library location
from plexapi.sync import VIDEO_QUALITY_ORIGINAL
locations = plex.library.section("Movies")._locations()
video.optimize(deviceProfile="iOS", videoQuality=VIDEO_QUALITY_ORIGINAL, locationID=locations[0])

# Optimize for tv the next 5 unwatched episodes
show.optimize(target="tv", limit=5, unwatched=True)

sync(videoQuality, client=None, clientId=None, limit=None, unwatched=False, title=None)[source]

Add current video (movie, tv-show, season or episode) as sync item for specified device. See sync() for possible exceptions.

Parameters:

videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module.
client (MyPlexDevice) – sync destination, see sync().
clientId (str) – sync destination, see sync().
limit (int) – maximum count of items to sync, unlimited if None.
unwatched (bool) – if True watched videos wouldn’t be synced.
title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current media.

Returns:

an instance of created syncItem.

Return type: