PYTHONPLEXAPI(1)

📦 version 4.18.1, in alpine 3.24

✨ NAME ✨

pythonplexapi — the Python PlexAPI docs, bestie. That's it, that's the name. Also hi, the manual is called Python PlexAPI and it lives at PYTHONPLEXAPI(1) in case you were wondering 🫶

💖 PYTHON-PLEXAPI 💖

🌸 Overview 🌸

Okay so — unofficial Python bindings for the Plex API. That's the whole vibe. Our goal is literally to match all the capabilities of the official Plex Web Client, no cap. A few of the many features we currently support are:

Navigate local or remote shared libraries 🗂️
Perform library actions such as scan, analyze, empty trash 🧹
Remote control and play media on connected clients, including Controlling Sonos speakers 🔊
Listen in on all Plex Server notifications 👀

🎀 Installation & Documentation 🎀

pip install plexapi

Install extra features:

pip install plexapi[alert]  # Install with dependencies required for plexapi.alert
pip install plexapi[jwt]    # Install with dependencies required for Plex JWT authentication

Documentation can be found at Read the Docs. Join our Discord for support and discussion — the link is on the docs site, iykyk ✨

🦋 Getting a PlexServer Instance 🦋

So there are two types of authentication, and picking one is giving main character energy. If you're running on a separate network or using Plex Users, you can log into MyPlex to get a PlexServer instance. Example below 👇

NOTE: Servername below is the name of the server (not the hostname and port). If logged into Plex Web you can see the server name in the top left above your available libraries 🎯

from plexapi.myplex import MyPlexAccount
account = MyPlexAccount('<USERNAME>', '<PASSWORD>')
plex = account.resource('<SERVERNAME>').connect()  # returns a PlexServer instance

If you want to avoid logging into MyPlex and you already know your auth token string, you can use the PlexServer object directly as above, by passing in the baseurl and auth token directly 💅

from plexapi.server import PlexServer
baseurl = 'http://plexserver:32400'
token = '2ffLuB84dqLswk9skLos'
plex = PlexServer(baseurl, token)

✨ Usage Examples ✨

These are the moment, fr fr:

# Example 1: List all unwatched movies.
movies = plex.library.section('Movies')
for video in movies.search(unwatched=True):
    print(video.title)

# Example 2: Mark all Game of Thrones episodes as played.
plex.library.section('TV Shows').get('Game of Thrones').markPlayed()

# Example 3: List all clients connected to the Server.
for client in plex.clients():
    print(client.title)

# Example 4: Play the movie Cars on another client.
# Note: Client must be on same network as server.
cars = plex.library.section('Movies').get('Cars')
client = plex.client("Michael's iPhone")
client.playMedia(cars)

# Example 5: List all content with the word 'Game' in the title.
for video in plex.search('Game'):
    print(f'{video.title} ({video.TYPE})')

# Example 6: List all movies directed by the same person as Elephants Dream.
movies = plex.library.section('Movies')
elephants_dream = movies.get('Elephants Dream')
director = elephants_dream.directors[0]
for movie in movies.search(None, director=director):
    print(movie.title)

# Example 7: List files for the latest episode of The 100.
last_episode = plex.library.section('TV Shows').get('The 100').episodes()[-1]
for part in last_episode.iterParts():
    print(part.file)

# Example 8: Get audio/video/all playlists
for playlist in plex.playlists():
    print(playlist.title)

# Example 9: Rate the 100 four stars.
plex.library.section('TV Shows').get('The 100').rate(8.0)

🔊 Controlling Sonos speakers 🔊

To control Sonos speakers directly using Plex APIs, the following requirements must be met — no skipping, bestie:

Active Plex Pass subscription 👑
Sonos account linked to Plex account 🔗
Plex remote access enabled 🌐

Due to the design of Sonos music services, the API calls to control Sonos speakers route through https://sonos.plex.tv and back via the Plex server's remote access. Actual media playback is local unless networking restrictions prevent the Sonos speakers from connecting to the Plex server directly 🧚

from plexapi.myplex import MyPlexAccount
from plexapi.server import PlexServer

baseurl = 'http://plexserver:32400'
token = '2ffLuB84dqLswk9skLos'

account = MyPlexAccount(token)
server = PlexServer(baseurl, token)

# List available speakers/groups
for speaker in account.sonos_speakers():
    print(speaker.title)

# Obtain PlexSonosPlayer instance
speaker = account.sonos_speaker("Kitchen")

album = server.library.section('Music').get('Stevie Wonder').album('Innervisions')

# Speaker control examples
speaker.playMedia(album)
speaker.pause()
speaker.setVolume(10)
speaker.skipNext()

🧪 Running tests over PlexAPI 🧪

Use:

tools/plex-boostraptest.py

with appropriate arguments and add this new server to a shared user which username is defined in environment variable SHARED_USERNAME. It uses official docker image to create a proper instance 🐳

For skipping the docker and reuse a existing server use:

python plex-bootstraptest.py --no-docker --username USERNAME --password PASSWORD --server-name NAME-OF-YOUR-SEVER

Also in order to run most of the tests you have to provide some environment variables:

PLEXAPI_AUTH_SERVER_BASEURL containing an URL to your Plex instance, e.g. http://127.0.0.1:32400 (without trailing slash)
PLEXAPI_AUTH_MYPLEX_USERNAME and PLEXAPI_AUTH_MYPLEX_PASSWORD with your MyPlex username and password accordingly

After this step you can run tests with following command:

py.test tests -rxXs --ignore=tests/test_sync.py

Some of the tests in main test-suite require a shared user in your account (e.g. test_myplex_users, test_myplex_updateFriend, etc.), you need to provide a valid shared user's username to get them running — you need to provide the username of the shared user as an environment variable SHARED_USERNAME. You can enable a Guest account and simply pass Guest as SHARED_USERNAME (or just create a user like plexapitest and play with it) 🎮

To be able to run tests over Mobile Sync api you have to some some more environment variables, to following values exactly:

PLEXAPI_HEADER_PROVIDES='controller,sync-target'
PLEXAPI_HEADER_PLATFORM=iOS
PLEXAPI_HEADER_PLATFORM_VERSION=11.4.1
PLEXAPI_HEADER_DEVICE=iPhone

And finally run the sync-related tests:

py.test tests/test_sync.py -rxXs

💜 Common Questions 💜

Why are you using camelCase and not following PEP8 guidelines?

This API reads XML documents provided by MyPlex and the Plex Server. We decided to conform to their style so that the API variable names directly match with the provided XML documents 📄

Why don't you offer feature XYZ?

This library is meant to be a wrapper around the XML pages the Plex server provides. If we are not providing an API that is offered in the XML pages, please let us know! -- Adding additional features beyond that should be done outside the scope of this library 🫶

What are some helpful links if trying to understand the raw Plex API?

💖 CONFIGURATION 💖

okay bestie so here's the tea: Python-PlexAPI will work fine without any configuration. like genuinely, out of the box, zero setup, she's ready. ✨ But sometimes there are things you may wish to alter for more control of the default behavior, and that's where this section comes in.

The default configuration file path is ~/.config/plexapi/config.ini, and you can override that whole situation by setting the environment variable PLEXAPI_CONFIG_PATH to whatever file path you desire. 🎀

All configuration variables in this file are optional. none of them are mandatory, they're just there if you want them. An example config.ini file may look like the following with all possible values specified:

# ~/.config/plexapi/config.ini
[plexapi]
container_size = 50
timeout = 30
timezone = false

[auth]
myplex_username = johndoe
myplex_password = kodi-stinks
server_baseurl = http://127.0.0.1:32400
server_token = XBHSMSJSDJ763JSm
client_baseurl = http://127.0.0.1:32433
client_token = BDFSLCNSNL789FH7

[header]
identifier = 0x485b314307f3L
platorm = Linux
platform_version = 4.4.0-62-generic
product = PlexAPI
version = 3.0.0

[log]
backup_count = 3
format = %(asctime)s %(module)12s:%(lineno)-4s %(levelname)-9s %(message)s
level = INFO
path = ~/.config/plexapi/plexapi.log
rotate_bytes = 512000
show_secrets = false

(yes platorm is spelled like that in the example, don't come for me, I'm just the messenger 💀)

🌈 Environment Variables 🌈

All configuration values can be set or overridden via environment variables. The environment variable names are in all upper case and follow the format PLEXAPI_<SECTION>_<NAME>. So like, if you wish to set the log path via an environment variable, you may specify:

PLEXAPI_LOG_PATH="/tmp/plexapi.log"

it's giving "no config file needed, just vibes in your shell". 🫶

✨ Section `[plexapi]` Options ✨

container_size — Default max results to return in one single search page. Looping through result pages is done internally by the API (so you don't gotta do it yourself, she handles it 💅). Therefore, tuning this setting will not affect usage of plexapi. However, it does help improve performance for large media collections (default: 50).
timeout — Timeout in seconds to use when making requests to the Plex Media Server or Plex Client resources (default: 30).
autoreload — By default PlexAPI will automatically reload() any PlexPartialObject when accessing a missing attribute. When this option is set to false, automatic reloading will be disabled and reload() must be called manually (default: true).
enable_fast_connect — By default Plex will be trying to connect with all available connection methods simultaneously, combining local and remote addresses, http and https, and be waiting for all connections to establish (or fail due to timeout / any other error). this can take a long time when you're trying to connect to your Plex Server outside of your home network 😭

When the option is set to true the connection procedure will be aborted with the first successfully established connection (default: false).

timezone — Controls whether toDatetime() returns timezone-aware datetime objects.
- false (default): keep naive datetime objects (backward compatible).
- true or local: use the local machine timezone.
- IANA timezone string (for example UTC or America/New_York): use that timezone.

This feature relies on Python's zoneinfo.ZoneInfo and the availability of IANA tzdata on the system. On platforms without system tzdata (notably Windows), you may need to install the tzdata Python package for IANA timezone strings (such as America/New_York) to work as expected. Toggling this option may break comparisons between aware and naive datetimes. ⚠️

🌸 Section `[auth]` Options 🌸

myplex_username — Default MyPlex (plex.tv) username to use when creating a new MyPlexAccount object. Specifying this along with auth.myplex_password allow you to more easily connect to your account and remove the need to hard code the username and password in any supplemental scripts you may write. To create an account object using these values you may simply specify account = MyPlexAccount() without any arguments (default: None).
myplex_password — Default MyPlex (plex.tv) password to use when creating a new MyPlexAccount object. See auth.myplex_password for more information and example usage (default: None).

WARNING: When specifying a password or token in the configuration file, be sure lock it down (permission 600) to ensure no other users on the system can read them. Or better yet, only specify sensitive values as a local environment variables. 🔐

server_baseurl — Default baseurl to use when creating a new PlexServer object. Specifying this along with auth.server_token allow you to more easily connect to a server and remove the need to hard code the baseurl and token in any supplemental scripts you may write. To create a server object using these values you may simply specify plex = PlexServer() without any arguments (default: None).
server_token — Default token to use when creating a new PlexServer object. See auth.server_baseurl for more information and example usage (default: None).

WARNING: When specifying a password or token in the configuration file, be sure lock it down (permission 600) to ensure no other users on the system can read them. Or better yet, only specify sensitive values as a local environment variables. 🔐

client_baseurl — Default baseurl to use when creating a new PlexClient object. Specifying this along with auth.client_token allow you to more easily connect to a client and remove the need to hard code the baseurl and token in any supplemental scripts you may write. To create a client object using these values you may simply specify client = PlexClient() without any arguments (default: None).
client_token — Default token to use when creating a new PlexClient object. See auth.client_baseurl for more information and example usage (default: None).

WARNING: When specifying a password or token in the configuration file, be sure lock it down (permission 600) to ensure no other users on the system can read them. Or better yet, only specify sensitive values as a local environment variables. 🔐

🦋 Section `[header]` Options 🦋

device — Header value used for X_PLEX_DEVICE to all Plex server and Plex client requests. Example devices include: iPhone, FireTV, Linux (default: result of platform.uname()[0]).
device_name — Header value used for X_PLEX_DEVICE_NAME to all Plex server and Plex client requests. Example device names include: hostname or phone name (default: result of platform.uname()[1]).
identifier — Header value used for X_PLEX_IDENTIFIER to all Plex server and Plex client requests. This is generally a UUID, serial number, or other number unique id for the device (default: result of hex(uuid.getnode())).
language — Header value used for X_PLEX_LANGUAGE to all Plex server and Plex client requests. This is an ISO 639-1 language code (default: en).
platform — Header value used for X_PLEX_PLATFORM to all Plex server and Plex client requests. Example platforms include: iOS, MacOSX, Android, LG (default: result of platform.uname()[0]).
platform_version — Header value used for X_PLEX_PLATFORM_VERSION to all Plex server and Plex client requests. This is generally the server or client operating system version: 4.3.1, 10.6.7, 3.2 (default: result of platform.uname()[2]).
product — Header value used for X_PLEX_PRODUCT to all Plex server and Plex client requests. This is the Plex application name: Laika, Plex Media Server, Media Link (default: PlexAPI).
provides — Header value used for X_PLEX_PROVIDES to all Plex server and Plex client requests. This is generally one or more of: controller, player, server (default: PlexAPI).
version — Header value used for X_PLEX_VERSION to all Plex server and Plex client requests. This is the Plex application version (default: plexapi.VERSION). 👑

🎀 Section `[log]` Options 🎀

backup_count — Number backup log files to keep before rotating out old logs (default 3).
format — Log file format to use for plexapi logging. (default: '%(asctime)s %(module)12s:%(lineno)-4s %(levelname)-9s %(message)s'). Ref: ‐ https://docs.python.org/2/library/logging.html#logrecord-attributes
level — Log level to use when for plexapi logging (default: INFO).
path — File path to save plexapi logs to. If not specified, plexapi will not save logs to an output file (default: None).
rotate_bytes — Max size of the log file before rotating logs to a backup file (default: 512000 equals 0.5MB).
show_secrets — By default Plex will hide all passwords and token values when logging. Set this to 'true' to enable logging these secrets. This should only be done on a private server and only enabled when needed (default: false). 🙈

ngl bestie, that last one is literally a "do not do this unless you know exactly why" situation. secrets stay secret, periodt. 💅

🛠️ `run()` — the method that is the thread's whole personality

Literally the method that represents the thread's activity, bestie.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object's constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

🛑 `stop()` — ending it, gracefully

Stops the AlertListener thread. Once the notifier is stopped, it cannot be directly started again — no take-backs, no re-runs 😭. You must call startAlertListener() from a PlexServer instance if you want it back. That's the rules.

🚨 ALERT `PLEXAPI.ALERT` 🚨

🎧 `class plexapi.alert.AlertListener(server, callback: Callable = None, callbackError: Callable = None, ws_socket: <module 'socket' from '/usr/lib/python3.14/socket.py'> = None)`

Bases: Thread

So this one creates a websocket connection to the PlexServer so you can optionally receive alert notifications ✨. These alerts often include messages from Plex about media scans, plus updates to currently running Transcode Sessions 👀. This class implements threading.Thread, so to actually start monitoring alerts you must call .start() on the object once it's created. But when you call PlexServer.startAlertListener(), the thread gets started for you — slay, no extra work 💅.

Known state-values for timeline entries, with identifier=com.plexapp.plugins.library``:

0 — the item was created
1 — reporting progress on item processing
2 — matching the item
3 — downloading the metadata
4 — processing downloaded metadata
5 — the item processed
9 — the item deleted

Heads up 🫶: when the metadata agent is not set for the library, processing ends with state=1.

💖 Parameters

server (PlexServer) — the PlexServer this listener is connected to.
callback (func) — callback function to call on received messages. It gets sent a single argument data, which is a dictionary of data received from the server. Like:

def my_callback(data): ...

callbackError (func) — callback function to call on errors. It gets sent a single argument error, which contains the Error object. Like:

def my_callback(error): ...

ws_socket (socket) — the socket to use for the connection. If you don't specify one, a new socket gets created for you ✨.

🎵 AUDIO `PLEXAPI.AUDIO` 🎵

🌸 `class plexapi.audio.Audio(server, data, initpath=None, parent=None)`

Bases: PlexPartialObject, PlayedUnplayedMixin

The base class for all audio objects, including Artist, Album, and Track — it's giving main-character-of-the-whole-audio-library energy 👑.

📋 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.
distance (float) — Sonic Distance of the item from the seed item.
fields (List<Field>) — list of field objects.
guid (str) — Plex GUID for the artist, album, or track (plex://artist/5d07bcb0403c64029053ac4c).
images (List<Image>) — list of image objects.
index (int) — Plex index number (often the track number).
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 'audio' (useful for search filters).
moods (List<Mood>) — list of mood objects.
musicAnalysisVersion (int) — the Plex music analysis version for the item.
ratingKey (int) — unique key identifying the item.
summary (str) — summary of the artist, album, or track.
thumb (str) — URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
thumbBlurHash (str) — BlurHash string for thumbnail image.
title (str) — name of the artist, album, or track (Jason Mraz, We Sing, Lucky, etc.).
titleSort (str) — title to use when sorting (defaults to title).
type (str) — 'artist', 'album', or 'track'.
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)`

Returns the full URL for the audio item. Typically used for getting a specific track 🎧.

🔊 property `hasSonicAnalysis`

Returns True if the audio has been sonically analyzed. No cap, it's just a vibes check on the audio 🦋.

📲 `sync(bitrate, client=None, clientId=None, limit=None, title=None)`

Adds the current audio (artist, album, or track) as a sync item for a specified device. See sync() for possible exceptions 👀.

Parameters

bitrate (int) — maximum bitrate for synchronized music; better use one of the MUSIC_BITRATE_* values from 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 gets generated from metadata of the current media.

Returns — an instance of the created syncItem.

Return type — SyncItem

🧬 `sonicallySimilar(limit: int | None = None, maxDistance: float | None = None, **kwargs) -> List[TAudio]`

Returns a list of sonically similar audio items — your "more like this" era 💜.

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)`

Bases: Audio, ArtistMixins

Represents a single Artist. Literally the moment 💅.

📋 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).
audienceRating (float) — audience rating.
collections (List<Collection>) — list of collection objects.
countries (List<Country>) — list of 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.
rating (float) — artist rating (7.9; 9.8; 8.1).
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>).
ultraBlurColors (UltraBlurColors) — Ultra blur color object.

💿 `album(title)`

Returns the Album that matches the specified title.

Parameters

title (str) — title of the album to return.

📀 `albums(**kwargs)`

Returns a list of Album objects by the artist.

🎶 `track(title=None, album=None, track=None)`

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. Like, you gotta give it something bestie 😭.

🎼 `tracks(**kwargs)`

Returns a list of Track objects by the artist.

`get(title=None, album=None, track=None)`

Alias of track(). Same thing, different name, iykyk.

⬇️ `download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)`

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().

🔥 `popularTracks()`

Returns a list of Track popular tracks by the artist — the hits, fr fr.

📻 `station()`

Returns a Playlist artist radio station or None.

metadataDirectory (property) — bestie this one hands you the Plex Media Server data directory where the metadata lives. That's it, that's the whole vibe 💅

🎀 class `plexapi.audio.Album(server, data, initpath=None, parent=None)` 🎀

Bases: Audio, AlbumMixins

okay so this one reps a single Album. iconic. here's everything it's packing 👑

Variables

TAG (str) — 'Directory'
TYPE (str) — 'album'
audienceRating (float) — audience rating, yeah.
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.
ultraBlurColors (UltraBlurColors) — ultra blur color object ✨
viewedLeafCount (int) — number of items marked as played in the album view.
year (int) — year the album was released.

`track(title=None, track=None)`

returns the Track that matches the title you asked for. no cap.

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. like if you give it neither, it WILL be dramatic about it 😭

`tracks(**kwargs)`

returns a list of Track objects in the album. all of them. the whole playlist era.

`get(title=None, track=None)`

alias of track(). same energy, shorter name 🫶

`artist()`

returns the album's Artist. found family fr.

`download(savepath=None, keep_original_name=False, **kwargs)`

downloads 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().

`metadataDirectory` (property)

returns the Plex Media Server data directory where the metadata is stored. again. because we love consistency 💖

🦋 class `plexapi.audio.Track(server, data, initpath=None, parent=None)` 🦋

Bases: Audio, Playable, TrackMixins

represents a single Track. the main character of the audio section, honestly.

Variables

TAG (str) — 'Directory'
TYPE (str) — 'track'
audienceRating (float) — audience rating.
chapters (List<Chapter>) — list of Chapter objects.
chapterSource (str) — Unknown. (yes literally "Unknown", we don't make the rules 🙈)
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>).
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) — (no notes on this one, it's just… there 💀)
rating (float) — track rating (7.9; 9.8; 8.1).
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. we've all been there.
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.

`locations` (property)

heads up bestie: 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. slay.

`trackNumber` (property)

returns the track number. short and sweet, we love her.

`album()`

return the track's Album.

`artist()`

return the track's Artist.

`metadataDirectory` (property)

returns the Plex Media Server data directory where the metadata is stored.

`sonicAdventure(to: TTrack, **kwargs: Any) -> list[TTrack]`

returns a sonic adventure from the current track to the specified track. like a little musical road trip, lowkey obsessed 🎧

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)` 🌈

Bases: PlexSession, Track

represents a single Track session loaded from sessions(). it's giving "who's listening right now" energy.

🌸 class `plexapi.audio.TrackHistory(server, data, initpath=None, parent=None)` 🌸

Bases: PlexHistory, Track

represents a single Track history entry loaded from history(). the receipts, basically 🧾

🌱 BASE PLEXAPI.BASE 🌱

class `plexapi.base.cached_data_property(func)`

Bases: cached_property

caching for PlexObject data properties. the way this decorator works: it creates properties that cache their values, with automatic invalidation whenever the data changes. so it's smart, it's self-cleaning, we stan ✨

class `plexapi.base.PlexObjectMeta(name, bases, attrs)`

Bases: type

metaclass for PlexObject to handle cached_data_properties. behind-the-scenes icon behavior, iykyk.

class `plexapi.base.PlexObject(server, data, initpath=None, parent=None)`

Bases: object

the base class for all Plex objects. mother of the entire family tree fr fr 💖

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)`

load the specified key to find and build all items with the specified tag and attrs. it's the "go get me everything" method and honestly it eats every time 🔥

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. kinda genius ngl.
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 carrying that exact tag, no substitutes 💅
container_start (None, int) — the offset, so you can grab just a lil subset of the data instead of the whole thing
container_size (None, int) — how many items live in the data
maxresults (int, optional) — cap it: only return this many results, periodt
params (dict, optional) — any extra params you wanna add to the request
**kwargs (dict) — optionally add an XML attribute to filter the items. Scroll down for the deets 👇

✨ Filtering XML Attributes ✨

Okay so this is the fun part: literally any XML attribute can be filtered when you're fetching results 🎀. And the filtering happens before the Python objects get built, which keeps things speedy — highkey a slay. So for example, passing in viewCount=0 will only return matching items where the view count is 0. Ngl, case matters when you're specifying attributes, so watch that. And attributes further down the XML tree can be filtered by prepending the attribute with each element tag plus a Tag__. Yes, double underscore. Iconic.

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)

Fr fr, that last line is copied verbatim — the closing quote really is missing in the original. Not me fixing it, bestie. 🙈

Also, because some attribute names are already used as arguments to this function — like tag — you can still reference the attr tag by prepending an underscore. So passing in _tag='foobar' will return all items where tag='foobar'. Sneaky but it works 💜.

🌈 Using PlexAPI Operators 🌈

Optionally — and this is where it gets good — PlexAPI operators can be specified by appending them to the end of the attribute for more complex lookups. So passing in viewCount__gte=0 will return all items where viewCount >= 0. Chef's kiss.

List of Available Operators:

__contains — value contains the specified arg
__endswith — value ends with the specified arg
__exact — value matches the specified arg
__exists (bool) — value is or is not present in the attrs
__gt — value is greater than the specified arg
__gte — value is greater than or equal to the specified arg
__icontains — case insensitive, value contains the specified arg
__iendswith — case insensitive, value ends with the specified arg
__iexact — case insensitive, value matches the 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 the specified arg
__lt — value is less than the specified arg
__lte — value is less than or equal to the specified arg
__regex — value matches the specified regular expression
__startswith — value starts with the 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)

Loads the specified key to find and build the first item with the specified tag and attrs. If you don't give it a tag or attrs, then the first item in the result set comes back. Simple as that ✨

Parameters 🫶

ekey (str or int) — path in Plex to fetch items from. If you pass in an int, the key gets translated to /library/metadata/<key>, which is lowkey a lifesaver: it means you can fetch an item knowing only its key-id
cls (PlexObject) — if you already know the class of the items being fetched, pass it in and the parser will make sure it only returns those items. By default it converts the XML elements into the best-guess PlexObjects based on the tag and type attrs
etag (str) — only fetch items with the specified tag
**kwargs (dict) — optionally add XML attributes to filter the items. See fetchItems() for more details on how this is used 💖

findItems(data, cls=None, initpath=None, rtag=None, **kwargs)

Loads 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. Iconic sibling energy 🎀

findItem(data, cls=None, initpath=None, rtag=None, **kwargs)

Loads the specified data to find and build the first item with the specified tag and attrs. Again, see fetchItem() for the deets. 👑

firstAttr(*attrs)

Returns the first attribute in attrs that isn't None. First come, first served, no cap 🦋

listAttrs(data, attr, rtag=None, **kwargs)

Returns a list of values from the matching attribute. A whole list of them, bestie 💅

reload(key=None, **kwargs)

Reloads the data for this object. The glow-up method, honestly ✨

Parameters

key (string, optional) — override the key to reload
**kwargs (dict) — a dictionary of XML include parameters to include/exclude or override. See PlexPartialObject for all the available include parameters. Set a parameter to True to include it and False to exclude it

Example ⭐

from plexapi.server import PlexServer
plex = PlexServer('http://localhost:32400', token='xxxxxxxxxxxxxxxxxxxx')

# Search results are partial objects.
movie = plex.library.section('Movies').get('Cars')
movie.isPartialObject()  # Returns True

# Partial reload of the movie without a default include parameter.
# The movie object will remain as a partial object.
movie.reload(includeMarkers=False)
movie.isPartialObject()  # Returns True

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

# Full reload of the movie with all default and extra include parameter.
# Including `checkFiles` will tell the Plex server to check if the file
# still exists and is accessible.
# The movie object will be a full object.
movie.reload(checkFiles=True)
movie.isFullObject()  # Returns True

class plexapi.base.PlexPartialObject(server, data, initpath=None, parent=None)

Bases: PlexObject

Okay so real talk: not all objects in the Plex listings return the complete list of elements for the object. This class is the fix 💖. It lets you assume each object is complete, and if the value you requested is None, it'll fetch the full object automatically and update itself. Main character energy fr fr 👑

analyze()

Tells Plex Media Server to perform analysis on this item to gather information. And 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 is automatically grabbed from a video file. A background image gets pulled out as well as a smaller image to be used for poster/thumbnail type purposes.
Generate Video Preview Thumbnails: video preview thumbnails get 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. Heads up: video preview thumbnail creation is a CPU-intensive process akin to transcoding the file 😭🔥 — like, it will work your CPU.
Generate intro video markers: detects show intros, exposing the 'Skip Intro' button in clients. The most iconic button of all time tbh.

isFullObject()

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 contains a portion of the attributes that a full object (main url) for that movie would contain. 🦋

isPartialObject()

Returns True if this is not a full object. The vibe check of object completeness 💅

isLocked(field: str)

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

Parameters

field (str) — the name of the field 🎀

edit(**kwargs)

Edits an object. Note: this is a low level method and you need to know all the field/tag keys. See EditFieldMixin and EditTagsMixin for the individual field and tag editing methods. Don't come at me if you raw-dog this one, bestie 🙈

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()`

okay bestie this one is a time-saver 💅 it turns on batch editing mode so you're not firing off a million separate API calls like some kind of maniac. You literally must call saveEdits() at the end or none of your edits actually land. If you wanna know about editing individual fields vs. tags, go peek at EditFieldMixin and EditTagsMixin.

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()`

Saves all your batch edits 💾 that's the whole vibe. Heads up though — the object needs to be reloaded manually if you want the fresh data. See batchEdits() above for the deets.

`refresh()`

Refreshing a Library or an individual item makes the metadata get refreshed — even if it already has metadata. Think of it like: "update the metadata for the thing I asked for, even if it's already got some." Not me explaining it like that but it's actually true 🫶

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()`

Returns the LibrarySection this item belongs to 🗂️ iykyk.

`delete()`

Deletes a media element 💀 but like — this has to be enabled under settings > server > library in the plex webui first, so don't come crying to me if it doesn't work.

`history(maxresults=None, mindate=None)`

Grabs the 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)`

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)`

Returns a new PlayQueue from this media item 🎶 See create() for the available parameters.

🦋 class `plexapi.base.Playable`

Bases: object

This is a mixin that stores functions specific to media that is Playable. Things were getting mixed up a lil bit when dealing with Shows, Season, Artists, Albums — which are all not playable, bestie. So we fixed it 💅

Variables

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

`getStreamURL(**kwargs)`

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()`

Iterates over the parts of this media item 🔁

`videoStreams()`

Returns a list of videoStream objects for all MediaParts 🎥

`audioStreams()`

Returns a list of AudioStream objects for all MediaParts 🔊

`subtitleStreams()`

Returns a list of SubtitleStream objects for all MediaParts 💬

`lyricStreams()`

Returns a list of LyricStream objects for all MediaParts 🎤

`play(client)`

Start playback on the specified client ▶️

Parameters

client (PlexClient) — Client to start playing on.

`download(savepath=None, keep_original_name=False, **kwargs)`

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')`

Set the watched progress for this video ⏱️

Bestie, note that setting the time to 0 will not work. Use markPlayed() or markUnplayed() if that's the goal, okay? 💖

Parameters

time (int) — milliseconds watched
state (string) — state of the video, default 'stopped'

`updateTimeline(time, state='stopped', duration=None)`

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`

Bases: object

Another mixin, this one storing 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 👑 it's giving main character energy fr.

`reload()`

Reload the data for the session 🔄 Note: this will return the object as-is if the session is no longer active. No cap.

`source()`

Return the source media object for the session 📼

`stop(reason='')`

Stop playback for the session ⏹️

Parameters

reason (str) — Message displayed to the user for stopping playback.

🎀 class `plexapi.base.PlexHistory`

Bases: object

Mixin time again 💅 this one stores 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()`

Return the source media object for the history entry, or None if the media no longer exists on the server 😭 rip.

`delete()`

Delete the history entry 🗑️

🧚 class `plexapi.base.MediaContainer`

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

Represents a single MediaContainer 📦 okay so it's literally a list and an object, iconic behaviour honestly.

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

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 🤷‍♀️ nobody knows bestie
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`

Extend list by appending elements from the iterable ➕ classic list behaviour, slay.

💻 CLIENT PLEXAPI.CLIENT

class `plexapi.client.PlexClient`

Bases: PlexObject

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

Okay so this is the main character class for talking to a Plex client 💅 — it can either connect straight to the client and control it directly, or proxy your commands through your Plex Server instead. If you wanna actually understand the Plex client API, the docs say to go read this page: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API 🫶

Parameters ✨

server (PlexServer) — the PlexServer this client is connected to (optional).
data (ElementTree) — the response from PlexServer that gets used to build this object (optional).
initpath (str) — path used to generate data.
baseurl (str) — HTTP URL for connecting directly to this client.
identifier (str) — the resource/machine identifier for the client you want. Might be needed when you're connecting to a specific proxied client (optional).
token (str) — the X-Plex-Token used for authentication (optional).
session (Session) — a requests.Session object, for when you want more control (optional).
timeout (int) — timeout in seconds on the initial connect to the client (defaults to config.TIMEOUT).

🦋 Variables 🦋

TAG (str) — 'Player'.
key (str) — '/resources'.
device (str) — best guess at what kind of device this is (PS, iPhone, Linux, etc).
deviceClass (str) — the device class (pc, phone, etc).
machineIdentifier (str) — the unique ID for this device.
model (str) — unknown.
platform (str) — unknown.
platformVersion (str) — description.
product (str) — the client product (Plex for iOS, etc).
protocol (str) — always seems to be 'plex' (yes, the docs literally say "ot be" 😭).
protocolCapabilities (list<str>) — list of client capabilities (navigation, playback, timeline, mirror, playqueues).
protocolVersion (str) — protocol version (1, future proofing?).
server (PlexServer) — the server this client is connected to.
session (Session) — the session object used for the connection.
state (str) — unknown.
title (str) — the name of this client (Johns iPhone, etc).
token (str) — X-Plex-Token used for authentication.
vendor (str) — unknown.
version (str) — the 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) — gets set to True after you call proxyThroughServer() (default False).

💜 Methods 💜

connect(timeout=None) — alias of reload, because any requests to this client after this point go directly to the device, even if the object's attributes were originally filled in from a PlexServer.
reload() — alias to self.connect().
proxyThroughServer(value=True, server=None) — tells this PlexClient instance to proxy all future commands through the PlexServer. Super handy if you don't wanna connect directly to the client device itself ✨

Parameters

value (bool) — enable or disable proxying (optional, default True).

Raises Unsupported — you cannot use client proxy with an unknown server.

query(path, method=None, headers=None, timeout=None, **kwargs) — the main method for handling HTTPS requests to the Plex client. It helps by encoding the response to utf-8 and parsing the returned XML into an ElementTree object. Returns None if there's no data in the response.
sendCommand(command, proxy=None, **params) — a convenience wrapper around query() so sending simple commands to the client is way easier. Returns an ElementTree object containing the response 🎀

Parameters

command (str) — the command to send, in the 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 that the client doesn't support this capability.

url(key, includeToken=False) — builds a URL string with the proper token argument. The token gets appended to the URL if either includeToken is True or CONFIG.log.show_secrets is 'true'.
contextMenu() — opens the context menu on the client.
goBack() — navigate back one position.
goToHome() — go straight to the home screen.
goToMusic() — go straight to the playing music panel.
moveDown() — move the selection down one position.
moveLeft() — move the selection left one position.
moveRight() — move the selection right one position.
moveUp() — move the selection up one position.
nextLetter() — jump to the next letter in the alphabet.
pageDown() — move the selection down a full page.
pageUp() — move the selection up a full page.
previousLetter() — jump to the previous letter in the alphabet.
select() — select the element at the current position.
toggleOSD() — toggle the on screen display during playback.
goToMedia(media, **params) — navigate directly to the specified media page.

Parameters

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

pause(mtype='video') — pause the currently playing media type.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

play(mtype='video') — start playback for the specified media type.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

refreshPlayQueue(playQueueID, mtype='video') — refresh the specified Playqueue.

Parameters

playQueueID (str) — Playqueue ID.
mtype (str) — the media type to take action against (music, photo, video).

seekTo(offset, mtype='video') — seek to the specified offset (in ms) during playback.

Parameters

offset (int) — position to seek to (milliseconds).
mtype (str) — the media type to take action against (music, photo, video).

skipNext(mtype='video') — skip to the next playback item.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

skipPrevious(mtype='video') — skip to the previous playback item.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

skipTo(key, mtype='video') — skip to the playback item with the specified key.

Parameters

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

stepBack(mtype='video') — step backward a chunk of time in the current playback item.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

stepForward(mtype='video') — step forward a chunk of time in the current playback item.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

stop(mtype='video') — stop the currently playing item.

Parameters

mtype (str) — the media type to take action against (music, photo, video).

setRepeat(repeat, mtype='video') — enable repeat for the specified playback items.

Parameters

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

setShuffle(shuffle, mtype='video') — enable shuffle for the specified playback items.

Parameters

shuffle (int) — shuffle mode (0=off, 1=on).
mtype (str) — the media type to take action against (music, photo, video).

setVolume(volume, mtype='video') — enable volume for the current playback item 🔊

Parameters

volume (int) — volume level (0-100).
mtype (str) — the media type to take action against (music, photo, video).

setAudioStream(audioStreamID, mtype='video') — select the audio stream for the current playback item (video only!).

Parameters

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

🎀 `setSubtitleStream(subtitleStreamID, mtype='video')`

Okay so this one picks the subtitle stream for whatever's playing right now — and yeah, only for video, bestie 💅

subtitleStreamID (str) — the ID of the subtitle stream, straight off the media object.
mtype (str) — which media type you're acting on (music, photo, video).

🦋 `setVideoStream(videoStreamID, mtype='video')`

Same vibe, but for video streams — selects the video stream for the current playback item (only video, obviously ✨).

videoStreamID (str) — the 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)`

Starts playback of the media item you hand it. See also: 👀

media (Media) — the media item to be played back (movie, music, photo, playlist, playqueue). So many options, we love versatility 💖
offset (int) — how many milliseconds in to start playing, where zero means the very beginning (default 0).
**params (dict) — optional extra parameters to shove into 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')`

Sets a whole bunch of playback parameters at once — efficiency queen 👑

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')`

And this one does all the streams in one go — literally the combo meal of stream selection 🍓

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)`

Polls the client's timelines, then creates and returns timeline objects. Heads up though: some clients just won't respond to timeline requests — apparently they believe this to be a Plex bug 😭 not us, we're just reporting it fr fr.

⭐ property `timeline`

Returns the active timeline object. Main character property energy 👑

💜 `isPlayingMedia(includePaused=True)`

Returns True if literally any media is currently playing.

includePaused (bool) — set True to treat currently paused items as playing (optional; default True).

🫶 class `plexapi.client.ClientTimeline(server, data, initpath=None, parent=None)`

Bases: PlexObject

Gets the timeline's attributes. That's the whole job and it does it slayfully ✨

🎀 COLLECTION PLEXAPI.COLLECTION 🎀

💖 class `plexapi.collection.Collection(server, data, initpath=None, parent=None)`

Bases: PlexPartialObject, CollectionMixins

Represents one single Collection. Just the one. Iconic behavior only 🌈

Variables (there's a lot, stay with me bestie):

TAG (str) — 'Directory'
TYPE (str) — 'collection'
addedAt (datetime) — when the collection got added to the library.
art (str) — URL to the artwork image (/library/metadata/<ratingKey>/art/<artid>).
artBlurHash (str) — BlurHash string for that artwork image.
audienceRating (float) — audience rating.
childCount (int) — how many items are 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 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).
images (List<Image>) — list of image objects.
index (int) — Plex index number for the collection.
key (str) — API URL (/library/metadata/<ratingkey>).
labels (List<Label>) — list of label objects.
lastRatedAt (datetime) — when 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.
rating (float) — collection rating (7.9; 9.8; 8.1).
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 items in the collection (movie, show, artist, or album).
summary (str) — summary of the collection.
theme (str) — URL to the theme resource (/library/metadata/<ratingkey>/theme/<themeid>).
thumb (str) — URL to the thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
thumbBlurHash (str) — BlurHash string for the thumbnail image.
title (str) — name of the collection.
titleSort (str) — title to use when sorting (defaults to title).
type (str) — 'collection'
ultraBlurColors (UltraBlurColors) — ultra blur color object ✨ aesthetic.
updatedAt (datetime) — when 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 inside 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()`

Returns the search filter dict for a smart collection. That filter dict gets passed right back into search() to get the list of items. Round trip, we love a cycle 🦋

🎀 `section()`

Returns the LibrarySection this collection belongs to. Found family fr fr 🫶

🍓 `item(title)`

Returns the item in the collection that matches the title you gave it.

title (str) — title of the item to return.

Raises plexapi.exceptions.NotFound — when the item is not found in the collection. 💀

⭐ `items()`

Returns a list of all items in the collection. All of them. No crumbs.

👑 `visibility()`

Returns the ManagedHub for this collection.

🧚 `get(title)`

Alias to item(). Same thing, cuter name.

💖 `filterUserUpdate(user=None)`

Updates the collection filtering user advanced setting.

user (str) — one of these values: "admin" (always the server admin user), "user" (user currently viewing the content).

Example

collection.updateMode(user="user")

🌸 `modeUpdate(mode=None)`

Updates the collection mode advanced setting.

mode (str) — one of these 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)`

Updates the collection order advanced setting.

sort (str) — one of these values: "release" (Order Collection by release dates), "alpha" (Order Collection alphabetically), "custom" (Custom collection order).

Example

collection.sortUpdate(sort="alpha")

🔥 `addItems(items)`

Adds items to the collection. Growing the collection, we love to see it 🌱

items (List) — list of Audio, Video, or Photo objects to be added to the collection.

Raises plexapi.exceptions.BadRequest — when you try to add items to a smart collection. Nope, not allowed, the smart ones handle themselves 😤

💀 `removeItems(items)`

Removes items from the collection. Sad but necessary.

items (List) — list of Audio, Video, or Photo objects to be removed from the collection.

Raises plexapi.exceptions.BadRequest — when you try to remove items from a smart collection. Same deal, smart collections are self-sufficient and will not be edited by you 💅

moveItem(item, after=None) — reposition an item inside the collection, like dragging a song up in your queue but make it official 💅

Parameters

item (obj) — the Audio, Video, or Photo object you wanna move in the collection.
after (obj) — the Audio, Video, or Photo object you want to move the item after in the collection.

Raises plexapi.exceptions.BadRequest — when you try to move items in a smart collection. yeah no, smart collections are built diff, you can't just shove things around in them 😭

updateFilters(libtype=None, limit=None, sort=None, filters=None, **kwargs) — update the filters on a smart collection. glow-up for your filter rules ✨

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 you try to update filters for a regular collection. regular collections said no thanks 🫶

delete() — delete the collection. it's over, bye bestie 💀
classmethod create(server, title, section, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs) — create a collection, fresh out the box 🎀

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. bestie you have to put something in it 😭
plexapi.exceptions.BadRequest — when mixing media types in the collection. don't mix, it's giving chaos.

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) — add the collection as a sync item for the specified device. take it offline, iconic behavior 💅

Parameters

videoQuality (int) — idx of quality of the video, one of VIDEO_QUALITY_* values defined in the sync module. Used only when the collection contains video.
photoResolution (str) — maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync. Used only when the collection contains photos.
audioBitrate (int) — maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync. Used only when the 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. no reruns for you ✋
title (str) — descriptive title for the new SyncItem, if empty the value would be generated from metadata of current photo.

Raises

BadRequest — when the collection is not allowed to sync.
Unsupported — when collection content is unsupported.

Returns a new instance of the created sync item.

Return type SyncItem

property metadataDirectory — returns the Plex Media Server data directory where the metadata is stored. that's where the lore lives 🗂️

🌸 CONFIG `PLEXAPI.CONFIG` 🌸

class plexapi.config.PlexConfig(path)

Bases: ConfigParser

PlexAPI configuration object, bestie. 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. iykyk 🧚

Parameters

path (str) — path of the configuration file to load.

get(key, default=None, cast=None)

Returns the specified configuration value or <default> if not found. literally the lookup girlie 💖

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()

Convenience function returns a dict of all base X-Plex-* headers for session requests. free real estate 🎁

💀 EXCEPTIONS `PLEXAPI.EXCEPTIONS` 💀

exception plexapi.exceptions.PlexApiException — Bases: Exception. Base class for all PlexAPI exceptions. the mother of all problems 😭
exception plexapi.exceptions.BadRequest — Bases: PlexApiException. An invalid request, generally a user error. we've all been there 🙈
exception plexapi.exceptions.NotFound — Bases: PlexApiException. Request media item or device is not found. it's giving lost in the sauce 🔍
exception plexapi.exceptions.UnknownType — Bases: PlexApiException. Unknown library type. no idea what that is bestie 🦋
exception plexapi.exceptions.Unsupported — Bases: PlexApiException. Unsupported client request. the client said no 💅
exception plexapi.exceptions.Unauthorized — Bases: BadRequest. Invalid username/password or token. security said not today 🔥
exception plexapi.exceptions.TwoFactorRequired — Bases: Unauthorized. Two factor authentication required. extra lock, extra slay 👑

class `plexapi.gdm.GDM`

Bases: object — it's the base class for discovering GDM services, bestie ✨

Variables

entries (List<dict>) — the list of server and/or client data that got discovered 👑
scan(scan_for_clients=False) — scan the network, go off 🔍
all(scan_for_clients=False) — return all found entries. It'll scan for entries if it hasn't scanned recently, no cap 💅
find_by_content_type(value) — return a list of entries that match the content_type 🎯
find_by_data(values) — return a list of entries that match the search parameters 🫶
update(scan_for_clients) — scan for new GDM services 🔥

Examples of the dict list assigned to self.entries by this function, literally here they are:

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() — test GDM discovery 🧪 ngl that's the whole job

🦋 LIBRARY PLEXAPI.LIBRARY 🦋

class `plexapi.library.Library(server, data, initpath=None, parent=None)`

Bases: PlexObject

Okay so this one represents a PlexServer library — it's got all the sections of media defined in your Plex server, including video, shows and audio. Main character energy honestly 👑

Variables

key (str) — '/library'
identifier (str) — Unknown ('com.plexapp.plugins.library')
mediaTagVersion (str) — Unknown (/system/bundle/media/flags/)
server (PlexServer) — the PlexServer this client is connected to 🫶
title1 (str) — 'Plex Library' (not sure how useful this is, genuinely 😭)
title2 (str) — second title (this is blank on my setup, fr)
sections() — returns a list of all media sections in this library. Library sections may be any of MovieSection, ShowSection, MusicSection, PhotoSection 💖
section(title) — 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, bestie 🎯

Parameters:

title (str) — title of the section to return.

Raises NotFound — the library section title is not found on the server.

sectionByID(sectionID) — 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) — 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) — returns a list of all media from all library sections. This may be a very large dataset to retrieve, so like… be aware 😭
onDeck() — returns a list of all media items on deck 🌈
recentlyAdded() — returns a list of all media items recently added ✨
search(title=None, libtype=None, **kwargs) — 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() — 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() — if a library has items in the Library Trash, use this option to empty the Trash 🗑️
optimize() — 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() — scan this library for new items 🔍
cancelUpdate() — cancel a library update, we love an undo button 🙈
refresh() — forces a download of fresh media information from the internet. This can take a long time. Any locked fields are not modified ⏳
deleteMediaPreviews() — delete the preview thumbnails for the all sections. This cannot be undone. Recreating media preview files can take hours or even days 😭 no cap, be careful
add(name='', type='', agent='', scanner='', location='', language='en-US', *args, **kwargs) — 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) — four letter language code (e.g. en-US)
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) — the country vibe check 🌍 default is 46, and here's the whole dropdown, no cap: 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) — pull in collection info from The Movie Database. Default is false 🎬
localart (bool) — prefer artwork that matches your library language. Default is true 🎨
adult (bool) — include adult content. Default is false 🙈
usage (bool) — send anonymous usage data to Plex. Default is true 📊

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

collections (bool) — use collection info from The Movie Database. Default is false.
localart (bool) — prefer artwork based on library language. Default is true.
adult (bool) — include adult content. Default is false.
country (int) — country (used for release date and content rating). Default is 47. Possible options, and yes the first one really is just an empty label, that's canon, don't come for me: 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) — pick your fighter: com.plexapp.agents.none, com.plexapp.agents.thetvdb, com.plexapp.agents.themoviedb, tv.plex.agents.series ✨
enableBIFGeneration (bool) — enable video preview thumbnails. Default is true 🎞️
episodeSort (int) — episode order. Default is -1. Possible options: 0:Oldest first, 1:Newest first.
flattenSeasons (int) — seasons. Default is 0. Possible options: 0:Show, 1:Hide.
includeInGlobal (bool) — include in dashboard. Default is 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 is true 🎬
native_subs (bool) — include extras with subtitles in Library language. Default is false 💬

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

collections (bool) — use collection info from The Movie Database. Default is false.
localart (bool) — prefer artwork based on library language. Default is true.
adult (bool) — include adult content. Default is false.
country (int) — country (used for release date and content rating). Default is 47. Options (again with the mystery 0: slot, she's iconic at this point): 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) — the lineup: com.plexapp.agents.none, com.plexapp.agents.imdb, com.plexapp.agents.themoviedb
enableBIFGeneration (bool) — enable video preview thumbnails. Default is true 🖼️
enableCinemaTrailers (bool) — enable Cinema Trailers. Default is true 🍿
includeInGlobal (bool) — include in dashboard. Default is true.
scanner (str) — Plex Movie Scanner, Plex Video Files Scanner

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

title (bool) — localized titles. Default is false.
extras (bool) — find trailers and extras automatically (Plex Pass required). Default is true.
only_trailers (bool) — skip extras which aren't trailers. Default is false.
redband (bool) — use red band (restricted audiences) trailers when available. Default is false 🔞
native_subs (bool) — include extras with subtitles in Library language. Default is false.
cast_list (int) — Cast List Source. Default is 1. Possible options: 0:IMDb, 1:The Movie Database.
ratings (int) — Ratings Source. Default is 0. Possible options: 0:Rotten Tomatoes, 1:IMDb, 2:The Movie Database.
summary (int) — Plot Summary Source. Default is 1. Possible options: 0:IMDb, 1:The Movie Database.
country (int) — Country. Default is 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 is false.
localart (bool) — prefer artwork based on library language. Default is true.
adult (bool) — include adult content. Default is false.
usage (bool) — send anonymous usage data to Plex. Default is true.

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

collections (bool) — use collection info from The Movie Database. Default is false.
localart (bool) — prefer artwork based on library language. Default is true.
adult (bool) — include adult content. Default is false.
country (int) — country (used for release date and content rating). Default is 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)`

history(maxresults=None, mindate=None)

Get Play History for all library Sections for the owner 💖 like a full receipts drop.

maxresults — only return the specified number of results, and it's optional. Type: int.
mindate — min datetime to return results from. Type: datetime ⏰

🏷️ `tags(tag)`

tags(tag)

Returns a list of LibraryMediaTag objects for the specified tag 🎀 give her a tag and she gives you the whole squad back.

Parameters

tag (str) — Tag name (see TAGTYPES).

🎀 `plexapi.library.LibrarySection`

class plexapi.library.LibrarySection(server, data, initpath=None, parent=None)

Bases: PlexObject

Okay bestie, this is the base class for a single library section — the main-character blueprint that all your movie/show/music library sections build on. 💖

🌸 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 represent 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)`

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()`

Delete a library section. 🗑️

`edit(agent=None, **kwargs)`

Edit a library. See Library for example usage.

Parameters

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

`addLocations(location)`

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)`

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)`

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)`

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)`

Returns a list of all items from this library section. See description of search() for details about filtering / sorting. 🦋

`folders()`

Returns a list of available Folder for this library section.

`managedHubs()`

Returns a list of available ManagedHub for this library section.

`resetManagedHubs()`

Reset the managed hub customizations for this library section.

`hubs()`

Returns a list of available Hub for this library section.

`agents()`

Returns a list of available Agent for this library section.

`settings()`

Returns a list of all library settings. ⚙️

`editAdvanced(**kwargs)`

Edit a library's advanced settings.

`defaultAdvanced()`

Edit all of library's advanced settings to default.

`lockAllField(field, libtype=None)`

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)`

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()`

Returns a timeline query for this library section. 📅

`onDeck()`

Returns a list of media items on deck from this library section. 🍿

`continueWatching()`

Return a list of media items in the library's Continue Watching hub. 👀

`recentlyAdded(maxresults=50, libtype=None)`

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()`

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

`emptyTrash()`

If a section has items in the Trash, use this option to empty the Trash. 🗑️✨

`update(path=None)`

Scan this section for new media.

Parameters

path (str, optional) — Full path to folder to scan.

`cancelUpdate()`

Cancel update of this Library Section. ✋

`refresh()`

Forces a download of fresh media information from the internet. This can take a long time. Any locked fields are not modified. 🌐

`deleteMediaPreviews()`

Delete the preview thumbnails for items in this library. This cannot be undone. Recreating media preview files can take hours or even days. 😭💀

`filterTypes()`

Returns a list of available FilteringType for this library section.

`getFilterType(libtype=None)`

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()` 💅

okay so this one just hands you back a list of every available FilteringFieldType for this library section. that's the whole thing. no cap, that's it.

`getFieldType(fieldType)` 🔍

gives you back one single FilteringFieldType for a specific fieldType. lowkey useful, honestly.

Parameters

fieldType (str) — the data type for the field. the valid ones are tag, integer, string, boolean, date, subtitleLanguage, audioLanguage, resolution.

Raises

NotFound — you asked for an unknown fieldType for this library. it's not a phase, it's just not there.

`listFilters(libtype=None)` 🎀

returns a list of every available FilteringFilter for a given libtype. this is literally the list of options you see in the filter dropdown menu (screenshot). so iconic of her.

Parameters

libtype (str, optional) — the library type to filter. options are 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)` ✨

returns a list of every available FilteringSort for a given libtype. this is the list of options in the sorting dropdown menu (screenshot). the way she sorts 💅

Parameters

libtype (str, optional) — the library type to filter. the choices are 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)` 🌸

returns a list of every available FilteringFields for a given libtype. these are the options in the custom filter dropdown menu (screenshot). bestie she's giving options.

Parameters

libtype (str, optional) — the library type to filter. pick from 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)` 🧚

returns a list of every available FilteringOperator for a given fieldType. this is the list of options in the custom filter operator dropdown menu (screenshot). yes, operators have their own moment.

Parameters

fieldType (str) — the data type for the field. valid ones: 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)` 🦋

returns a list of every available FilterChoice for a given FilteringFilter or filter field. this is the list of available values for a custom filter (screenshot). the whole menu, unlocked.

Parameters

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

Raises

BadRequest — invalid filter field. not her.
NotFound — unknown filter field. also not her.

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)` 🔥

returns the hub search results for this library. fr fr, see plexapi.server.PlexServer.search() for all the details and parameters — she's the main character of search.

`search(title=None, sort=None, maxresults=None, libtype=None, container_start=None, container_size=None, limit=None, filters=None, **kwargs)` 👑

searches the library. the http requests get batched in container_size. and here's a tip that will save your whole life: if you only want the first <num> results, set the maxresults option to that number so the search doesn't sit there iterating over all the results on the server. respectfully, don't make her do all that.

Parameters

title (str, optional) — a general string query to search for. partial string matches are allowed, so you don't need the whole title.
sort (FilteringSort or str or list, optional) — a field to sort the results by. the details live below 👇
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) — defaults to 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. details below 👇
**kwargs (dict) — additional custom filters to apply to the search results. details below 👇

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. periodt.

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 passing a FilteringSort object, will sort the results in the default direction of the field. multi-sorting on multiple fields is a vibe you can absolutely have — use 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). obsessed.

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 filter fields below are just some examples of the possible filters. this list is not exhaustive, and not all filters apply to all library types. iykyk.

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, a MediaTag object, the exact name MediaTag.tag (str), or the exact id MediaTag.id (int). any of those, bestie. she's flexible 💖

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

Relative date suffixes, memorise these:

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. Yes queen, list it up ✨

🎀 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

Okay so some filters may be prefixed by the libtype separated by a . (e.g. show.collection, episode.title, artist.style, album.genre, track.userRating, etc.). Do not confuse this with the libtype parameter, they are literally different things 🙈 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. iykyk 🧚

⭐ 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. Slay 💅

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. That's the rule, no cap 🫶

💖 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. It's giving decision tree, honestly iconic 🌈

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. Lowkey best of both worlds 💜

💀 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()`

sync(policy, mediaSettings, client=None, clientId=None, title=None, sort=None, libtype=None, **kwargs)

Add current library section as sync item for specified device. See description of search() for details about filtering / sorting and sync() for possible exceptions. It's giving "download this for me bestie" energy ✨

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 — SyncItem

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()`

history(maxresults=None, mindate=None)

Get Play History for this library Section for the owner. The receipts of what you watched 🎀

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

🧚 `createCollection()`

createCollection(title, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, **kwargs)

Alias for createCollection() using this LibrarySection. That's it, that's the whole vibe 💅

`collection(title)`

Gives you back the collection with that exact title.

Parameters:

title (str) — the title of the item you want back.

Raises NotFound — when it literally cannot find that collection. 😭

`collections(**kwargs)`

Returns a list of collections living in this library section. If you wanna know about filtering / sorting, go read the description of search() — it's all there, bestie.

`createPlaylist(title, items=None, smart=False, limit=None, sort=None, filters=None, m3ufilepath=None, **kwargs)`

Alias for createPlaylist() that uses this LibrarySection. Same energy, less typing. ✨

`playlist(title)`

Returns the playlist with that specified title.

Parameters:

title (str) — title of the item to return.

Raises NotFound — unable to find playlist. 💀

`playlists(sort=None, **kwargs)`

Returns a list of playlists from this library section.

`getWebURL(base=None, tab=None, key=None)`

Returns the Plex Web URL for the library. Cute, right? 🎀

Parameters:

base (str) — the base URL before the fragment (#!). Default is https://app.plex.tv/desktop.
tab (str) — the library tab, and your options are recommended, library, collections, playlists, timeline.
key (str) — a hub key.

`common(items)`

Returns a Common object for the items you pass in. 🫶

`multiEdit(items, **kwargs)`

Edits multiple objects at once. Heads up though — this is a low level method and you genuinely need to know all the field/tag keys. If that sounds like a lot, use 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)`

Turns on batch multi-editing mode so you save API calls. You must call saveMultiEdits() at the end to actually save all the edits — don't forget, or nothing sticks. For the individual field and tag editing methods, see EditFieldMixin and EditTagsMixin. 👑

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()`

Saves all the batch multi-edits. Details live over in batchMultiEdits(). 💖

🎬 class `plexapi.library.MovieSection(server, data, initpath=None, parent=None)`

Bases: LibrarySection, MovieEditMixins

Represents a LibrarySection section containing movies. Movie night is literally every night.

Variables:

TAG (str) — 'Directory'
TYPE (str) — 'movie'

`searchMovies(**kwargs)`

Search for a movie. See search() for usage. 🔍

`recentlyAddedMovies(maxresults=50)`

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)`

Adds the current Movie library section as a sync item for the specified device. For details about filtering / sorting, see the description of search(), and for details on syncing libraries and possible exceptions, see sync().

Parameters:

videoQuality (int) — idx of quality of the video, one of the VIDEO_QUALITY_* values defined in the 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: SyncItem

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)`

Bases: LibrarySection, ShowEditMixins, SeasonEditMixins, EpisodeEditMixins

Represents a LibrarySection section containing tv shows. Binge-watching is a personality trait, ngl.

Variables:

TAG (str) — 'Directory'
TYPE (str) — 'show'

`searchShows(**kwargs)`

Search for a show. See search() for usage. 🌸

`searchSeasons(**kwargs)`

Search for a season. See search() for usage. 🦋

`searchEpisodes(**kwargs)`

Search for an episode. See search() for usage. ⭐

`recentlyAddedShows(maxresults=50)`

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)`

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)`

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)`

Adds the current Show library section as a sync item for the specified device. For the filtering / sorting details, read the description of search(), and for the syncing-libraries details plus possible exceptions, read sync().

Parameters:

videoQuality (int) — idx of quality of the video, one of the VIDEO_QUALITY_* values defined in the 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: SyncItem

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)`

Bases: LibrarySection, ArtistEditMixins, AlbumEditMixins, TrackEditMixins

Represents a LibrarySection section containing music artists. The aux cord is yours, icon. 🔥

Variables:

TAG (str) — 'Directory'
TYPE (str) — 'artist'

`albums()`

Returns a list of Album objects in this section. 💜

`stations()`

Returns a list of Playlist stations in this section. 🎀

`searchArtists(**kwargs)`

Search for an artist. See search() for usage.

`searchAlbums(**kwargs)`

Search for an album. See search() for usage.

`searchTracks(**kwargs)`

Search for a track. See search() for usage.

`recentlyAddedArtists(maxresults=50)`

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)`

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)`

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)`

Adds the current Music library section as a sync item for the specified device. Filtering / sorting deets are in the description of search(), and syncing-libraries deets plus possible exceptions are in sync().

Parameters:

bitrate (int) — maximum bitrate for synchronized music, and honestly it's better to use one of the 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: SyncItem

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')

okay so that's literally the whole vibe — grab your Music section, sync it to the client, cap it at 100, newest first, name it 'New music'. Ate. 💖

sonicAdventure(start: Track | int, end: Track | int, **kwargs: Any) -> list[Track] — bestie this one hands you back 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. So like, keep it track IDs, iykyk. 🎧

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 — extra parameters to pass along 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)`

Bases: LibrarySection, PhotoalbumEditMixins, PhotoEditMixins

Represents a LibrarySection section containing photos. yes, the photo girly of the library family. 📸🌸

Variables

TAG (str) — 'Directory'
TYPE (str) — 'photo'

all(libtype=None, **kwargs) — returns a list of all items from this library section. Wanna know about filtering / sorting? See the description of plexapi.library.LibrarySection.search().

collections(**kwargs) — returns a list of collections from this library section. See the description of search() for the whole filtering / sorting situation.

searchAlbums(**kwargs) — searches for a photo album. See search() for how to use it.

searchPhotos(**kwargs) — searches for a photo. Again, search() is your girl for usage.

recentlyAddedAlbums(maxresults=50) — returns a list of recently added photo albums from this library section.

maxresults (int) — max number of items to return (default 50).

sync(resolution, limit=None, **kwargs) — adds the current Music library section as a sync item for the specified device. (yes it literally says Music in the photo section, we do not make the rules 💀) See the description of search() for filtering / sorting deets and sync() for the library-syncing tea and possible exceptions.

Parameters

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

Returns — an instance of the created syncItem.

Return type — SyncItem

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')

literally the same sync moment but for photos, title 'Fresh photos'. iconique. ✨

`class plexapi.library.LibraryTimeline(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a LibrarySection timeline. it's giving "what's the tea on this section's timeline" energy. 🕰️

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)`

Bases: PlexObject

Represents a single library Location. one path, living its best life. 📁

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)`

Bases: PlexObject

Represents a single Hub (or category) in the PlexServer search. like a lil curated shelf of content, slay. 🗂️

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 (automatically loads all items if more is True).
key (str) — API URL for the hub.
random (bool) — True if the items in the hub are randomized.
more (bool) — True if there are more items to load (call items 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.

items() — returns a list of all items in the hub.

section() — returns the LibrarySection this hub belongs to.

fr fr note: items shows up both as a variable and as a method here. yes that's really what the docs say. keep both. 😭

`class plexapi.library.LibraryMediaTag(server, data, initpath=None, parent=None)`

Bases: PlexObject

Base class of library media tags. the parent energy for all the tag girlies below. 👑

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) — returns the list of items within this tag. simple as that. 💅

`class plexapi.library.Aperture(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Aperture library media tag.

Variables — TAGTYPE (int) — 202

`class plexapi.library.Art(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Art library media tag.

Variables — TAGTYPE (int) — 313

`class plexapi.library.Autotag(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Autotag library media tag.

Variables — TAGTYPE (int) — 207

`class plexapi.library.Chapter(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Chapter library media tag.

Variables — TAGTYPE (int) — 9

`class plexapi.library.Collection(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Collection library media tag. (different from the top-level plexapi.collection one — this is the library tag version, don't mix them up bestie 🫶)

Variables — TAGTYPE (int) — 2

`class plexapi.library.Concert(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Concert library media tag.

Variables — TAGTYPE (int) — 306

`class plexapi.library.Country(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Country library media tag.

Variables — TAGTYPE (int) — 8

`class plexapi.library.Device(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Device library media tag.

Variables — TAGTYPE (int) — 206

`class plexapi.library.Director(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Director library media tag.

Variables — TAGTYPE (int) — 4

`class plexapi.library.Exposure(server, data, initpath=None, parent=None)`

Bases: LibraryMediaTag

Represents a single Exposure library media tag.

Variables — TAGTYPE (int) — 203

🌈 the tag squad (aka every `LibraryMediaTag` subclass, all lined up)

okay bestie, this is the part where the manpage just absolutely spams you with tiny classes, and honestly? each one is giving "same energy, different number" 💅 so here's the whole crew. every single one of them takes the same constructor — literally identical, no cap:

(server, data, initpath=None, parent=None)

and every one of them has Bases: LibraryMediaTag. the only thing that changes is the description and the TAGTYPE int. so let's go, one by one, no skipping, i promise 🫶

plexapi.library.Format — Represents a single Format library media tag. ✨
- Signature: class plexapi.library.Format(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 302
plexapi.library.Genre — Represents a single Genre library media tag. 🎀
- Signature: class plexapi.library.Genre(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 1
plexapi.library.Guid — Represents a single Guid library media tag. 🦋
- Signature: class plexapi.library.Guid(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 314
plexapi.library.ISO — Represents a single ISO library media tag. 📀
- Signature: class plexapi.library.ISO(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 204
plexapi.library.Label — Represents a single Label library media tag. 🏷️
- Signature: class plexapi.library.Label(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 11
plexapi.library.Lens — Represents a single Lens library media tag. 🔍
- Signature: class plexapi.library.Lens(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 205
plexapi.library.Make — Represents a single Make library media tag. 🚗
- Signature: class plexapi.library.Make(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 200
plexapi.library.Marker — Represents a single Marker library media tag. 📍
- Signature: class plexapi.library.Marker(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 12
plexapi.library.MediaProcessingTarget — Represents a single MediaProcessingTarget library media tag. 💅 this one is different from the rest, bestie, it's got two variables so pay attention 😭
- Signature: class plexapi.library.MediaProcessingTarget(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAG (str) — 'Tag'
- TAGTYPE (int) — 42
plexapi.library.Model — Represents a single Model library media tag. ✨
- Signature: class plexapi.library.Model(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 201
plexapi.library.Mood — Represents a single Mood library media tag. 🌧️
- Signature: class plexapi.library.Mood(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 300
plexapi.library.Network — Represents a single Network library media tag. 📺
- Signature: class plexapi.library.Network(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 319
plexapi.library.Place — Represents a single Place library media tag. 🌍
- Signature: class plexapi.library.Place(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 400
plexapi.library.Poster — Represents a single Poster library media tag. 🖼️
- Signature: class plexapi.library.Poster(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 312
plexapi.library.Producer — Represents a single Producer library media tag. 🎬
- Signature: class plexapi.library.Producer(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 7
plexapi.library.RatingImage — Represents a single RatingImage library media tag. ⭐
- Signature: class plexapi.library.RatingImage(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 316
plexapi.library.Review — Represents a single Review library media tag. 📝
- Signature: class plexapi.library.Review(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 10
plexapi.library.Role — Represents a single Role library media tag. 🎭
- Signature: class plexapi.library.Role(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 6
plexapi.library.Similar — Represents a single Similar library media tag. 👯
- Signature: class plexapi.library.Similar(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 305
plexapi.library.Studio — Represents a single Studio library media tag. 🏢
- Signature: class plexapi.library.Studio(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 318
plexapi.library.Style — Represents a single Style library media tag. 💃
- Signature: class plexapi.library.Style(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 301
plexapi.library.Tag — Represents a single Tag library media tag. 🏷️ and yes, the class called Tag has TAGTYPE zero, iconic of it honestly
- Signature: class plexapi.library.Tag(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 0
plexapi.library.Theme — Represents a single Theme library media tag. 🎵
- Signature: class plexapi.library.Theme(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 317
plexapi.library.Writer — Represents a single Writer library media tag. ✍️
- Signature: class plexapi.library.Writer(server, data, initpath=None, parent=None)
- Bases: LibraryMediaTag
- TAGTYPE (int) — 5

🌸 the filtering girlies — `FilteringType`, `FilteringFilter`, `FilteringSort`, `FilteringField`, `FilteringFieldType`, `FilteringOperator`

bestie these are the ones that make the search filters actually go ✨ they're not tags, they're the scaffolding behind filtering. all of them are Bases: PlexObject, and they all take the same constructor shape:

(server, data, initpath=None, parent=None)

plexapi.library.FilteringType — Represents a single filtering Type object for a library. 👑

class plexapi.library.FilteringType(server, data, initpath=None, parent=None)

Bases: PlexObject

Variables, all of them, no skimping 💖:

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.

plexapi.library.FilteringFilter — Represents a single Filter object for a FilteringType. 🎀

class plexapi.library.FilteringFilter(server, data, initpath=None, parent=None)

Bases: PlexObject

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'

plexapi.library.FilteringSort — Represents a single Sort object for a FilteringType. 🔀

class plexapi.library.FilteringSort(server, data, initpath=None, parent=None)

Bases: PlexObject

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.

ngl the default vs active vs defaultDirection vs activeDirection quartet is a whole vibe check on its own — they're four separate strings, don't merge them in ur head 😭

plexapi.library.FilteringField — Represents a single Field object for a FilteringType. 🌾

class plexapi.library.FilteringField(server, data, initpath=None, parent=None)

Bases: PlexObject

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).

plexapi.library.FilteringFieldType — Represents a single FieldType for library filtering. 🧚

class plexapi.library.FilteringFieldType(server, data, initpath=None, parent=None)

Bases: PlexObject

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

plexapi.library.FilteringOperator — Represents an single Operator for a FilteringFieldType. ⚙️ (yes the original says "an single", we are preserving the lore fr fr)

class plexapi.library.FilteringOperator(server, data, initpath=None, parent=None)

Bases: PlexObject

TAG (str) — 'Operator'
key (str) — The URL key for the operator.
title (str) — The title of the operator.

🦋 `FilterChoice` — the one you'll actually see in ur results

plexapi.library.FilterChoice — Represents a single FilterChoice object. these are the little darlings you get handed back when you use filters while searching for library items — it's literally the object returned in the result set of listFilterChoices(). main character energy, truly 👑

class plexapi.library.FilterChoice(server, data, initpath=None, parent=None)

Bases: PlexObject

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).

and she has a method, bestie, one little method 🥺:

items() — Returns a list of items for this filter choice.

💜 `ManagedHub` — the recommendation girlie

plexapi.library.ManagedHub — Represents a Managed Hub (recommendation) inside a library. 🌈 this is the curated shelf vibe, the "here's what we think u should watch" of it all.

class plexapi.library.ManagedHub(server, data, initpath=None, parent=None)

Bases: PlexObject

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.
move(after=None) — slides a managed hub to a whole new spot in the library's Managed Recommendations, like rearranging your playlists until it hits.
- after (obj) — the ManagedHub object you want to drop this item after in the collection.
- Raises plexapi.exceptions.BadRequest — throws this when you're trying to move a Hub that isn't a Managed Recommendation. rude but fair 💅
remove() — yeets a managed hub out of the library's Managed Recommendations entirely.
- Raises plexapi.exceptions.BadRequest — when you try to remove a Hub that isn't a Managed Recommendation, or when the Hub genuinely cannot be removed. no cap, it'll fight you 🫠
updateVisibility(recommended=None, home=None, shared=None) — glow-up time: flip the managed hub's visibility settings all at once.
- Parameters:
  - recommended (bool) — True makes it visible on your Library Recommended page, False hides it. Default None.
  - home (bool) — True makes it visible on your Home page, False hides it. Default None.
  - shared (bool) — True makes it visible on your Friends' Home page, False hides it. Default None.
- Example:

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

promoteRecommended() — puts the managed hub on your Library Recommended Page. main character energy ✨
demoteRecommended() — hides the managed hub from your Library Recommended Page. ghosting, but polite.
promoteHome() — shows the managed hub on your Home Page. 🏠
demoteHome() — hides the manged hub from your Home Page. (yep, that typo is canon, we keep it fr fr 🙈)
promoteShared() — shows the managed hub on your Friends' Home Page. sharing is caring 🫶
demoteShared() — hides the managed hub from your Friends' Home Page.

🗂️ class `plexapi.library.Folder(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a Folder inside a library. lowkey just a folder, but make it Plex.

Variables:

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

Methods:

subfolders() — returns a list of available Folder for this folder. It keeps going down subfolders until a mediaType is found, like digging through your downloads folder at 2am. 🕳️
allSubfolders() — returns a list of all available Folder for this folder. Only returns Folder. that's it, that's the whole vibe.

🔤 class `plexapi.library.FirstCharacter(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a First Character element from a library. the alphabet, but make it metadata 👑

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)`

Bases: PlexObject

Represents a single directory Path. one (1) folder, no notes.

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

Methods:

browse(includeFiles=True) — alias for browse().
walk() — alias for walk().

yes bestie, those aliases literally alias themselves in the docs. we don't question the source material, we just report it 💀

📄 class `plexapi.library.File(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single File. one file. that's the post.

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)`

Bases: PlexObject

Represents a Common element from a library. This object lists common fields between multiple objects — like a group chat where everyone shares the same interests. 🫂

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.

Properties & methods:

property commonType — returns the media type of the common items.
property ratingKeys — returns a list of rating keys for the common items.
items() — returns a list of the common items.

🎬 MEDIA PLEXAPI.MEDIA

📼 class `plexapi.media.Media(server, data, initpath=None, parent=None)`

Bases: PlexObject

Container object for all MediaPart objects. It hands you the useful deets about the video or audio this media belongs to — video framerate, resolution, all of it. the lore is rich, bestie 📚

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.
hasVoiceActivity (bool) — True if video has voice activity analyzed.
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. pics only, babes 📸
- 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:

property isOptimizedVersion — returns True if the media is a Plex optimized version.

🎞️ class `plexapi.media.MediaPart(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single media part (often a single file) for the media this belongs to. like, the actual file behind the whole vibe.

Variables:

TAG (str) — 'Part'
accessible (bool) — True if the file is accessible. Requires reloading the media with checkFiles=True. Refer to reload().
audioProfile (str) — The audio profile of the file.

okay bestie we're still in the MediaPart variable list, buckle up, it's a long one 💖

container (str) — the container type of the file (ex: avi).
decision (str) — literally unknown. nobody knows. it's giving mystery ✨.
deepAnalysisVersion (int) — the Plex deep analysis version for the file.
duration (int) — how long the file is, in milliseconds.
exists (bool) — True if the file actually exists. ⚠️ heads up: you gotta reload the media with checkFiles=True first, check reload() for that.
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>) — a list of stream objects.
syncItemId (int) — the unique ID for this media part if it's 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. same energy as indexes but as a cute lil property 🫶

`videoStreams()`

Returns a list of VideoStream objects in this MediaPart. iykyk.

`audioStreams()`

Returns a list of AudioStream objects in this MediaPart.

`subtitleStreams()`

Returns a list of SubtitleStream objects in this MediaPart.

`lyricStreams()`

Returns a list of LyricStream objects in this MediaPart. yes bestie, lyrics too 🎤✨

`setSelectedAudioStream(stream)`

Set the selected AudioStream for this MediaPart.

Parameters

stream (AudioStream) — audio stream to set as selected.

`setSelectedSubtitleStream(stream)`

Set the selected SubtitleStream for this MediaPart.

Parameters

stream (SubtitleStream) — subtitle stream to set as selected.

`resetSelectedSubtitleStream()`

Set the selected subtitle of this MediaPart to 'None'. bye bye subs 👋 literally just turns them off.

### class `plexapi.media.MediaPartStream`

plexapi.media.MediaPartStream(server, data, initpath=None, parent=None)

Bases: PlexObject

Base class for media streams. these are the video, audio, subtitles, and lyrics ones — the whole squad 🧚

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, ไทย). multilingual queen 💅
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. same thing, different font 💖

### class `plexapi.media.VideoStream`

plexapi.media.VideoStream(server, data, initpath=None, parent=None)

Bases: MediaPartStream

Represents a video stream within a MediaPart. the visual main character ✨

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. fancy 💅
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`

plexapi.media.AudioStream(server, data, initpath=None, parent=None)

Bases: MediaPartStream

Represents a audio stream within a MediaPart. sound bestie 🎧

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.
visualImpaired (bool) — True if this is a visually impaired (AD) audio stream.
Track_only_attributes —

The following attributes are only available for tracks. 👀 not all of them, just 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()`

Sets this audio stream as the selected audio stream. it's an alias for setSelectedAudioStream(), so pick whichever one you vibe with 🫶

`levels(subSample=128)`

Returns a list of Level objects for this AudioStream. ⚠️ only available for Tracks which have been analyzed for loudness — no analysis, no levels, periodt.

Variables

subSample (int) — the number of loudness samples to return. default 128.

### class `plexapi.media.SubtitleStream`

plexapi.media.SubtitleStream(server, data, initpath=None, parent=None)

Bases: MediaPartStream

Represents a audio stream within a MediaPart.

Variables

(and we're picking the subtitle vibe check up right here in the next bit — don't go anywhere bestie 💖)

TAG (str) — 'Stream' 💅
STREAMTYPE (int) — 3
canAutoSync (bool) — True if this subtitle stream can be auto synced. like, it's allowed to just show up on its own ✨
container (str) — the container of the subtitle stream
forced (bool) — True if this is a forced subtitle (iykyk, the "alien language only" ones 🛸)
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. no notes, chef's kiss 👑
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 🙈 (yes bestie, the docs literally say Unknown, we don't make the rules)
userID (int) — the user id of the user that downloaded the on-demand subtitle

`setSelected()`

Sets this subtitle stream as the selected subtitle stream. It's an alias for setSelectedSubtitleStream() — same energy, two names, slay 💅

class `plexapi.media.LyricStream(server, data, initpath=None, parent=None)`

Bases: MediaPartStream

Represents a lyric stream within a MediaPart. Karaoke night is so on 🎤✨

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)`

Bases: PlexObject

Represents a current session. it's giving "who's watching right now" main character energy 👀

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)`

Bases: PlexObject

Represents a current transcode session. buckle up bestie, this one has a lot of variables 🔥

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)`

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)`

Bases: PlexObject

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

`items()`

Returns a list of all Video objects in this optimized item.

`remove()`

Remove an Optimized item

`rename(title)`

Rename an Optimized item

`reprocess(ratingKey)`

Reprocess a removed Conversion item that is still a listed Optimize item ♻️

class `plexapi.media.Conversion(server, data, initpath=None, parent=None)`

Bases: PlexObject

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

`remove()`

Remove Conversion from queue

`move(after)`

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)`

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. it's the whole "how do I even find this" system bestie 🏷️✨

Variables

filter (str) — the library filter for the tag
id (int) — 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()`

Return the list of items within this tag.

class `plexapi.media.Collection(server, data, initpath=None, parent=None)`

Bases: MediaTag

Represents a single Collection media tag.

Variables

TAG (str) — 'Collection'
FILTER (str) — 'collection'

`collection()`

Return the Collection object for this collection tag.

class `plexapi.media.Country(server, data, initpath=None, parent=None)`

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)`

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)`

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)`

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)`

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)`

Bases: MediaTag

Represents a single Mood media tag. the vibe check, literally 🌸

Variables

TAG (str) — 'Mood'
FILTER (str) — 'mood'

class `plexapi.media.Producer(server, data, initpath=None, parent=None)`

Bases: MediaTag

Represents a single Producer media tag.

Variables

TAG (str) — 'Producer'
FILTER (str) — 'producer'

🦋 `plexapi.media.Role`

class plexapi.media.Role(server, data, initpath=None, parent=None)

Bases: MediaTag

okay so this one represents a single Role media tag — like an actor or actress tag, yk? 💅

Variables (the whole vibe check):

TAG (str) — 'Role'
FILTER (str) — 'role'

🌸 `plexapi.media.Similar`

class plexapi.media.Similar(server, data, initpath=None, parent=None)

Bases: MediaTag

Represents a single Similar media tag. bestie it's the "you might also like" energy ✨

Variables:

TAG (str) — 'Similar'
FILTER (str) — 'similar'

🎀 `plexapi.media.Style`

class plexapi.media.Style(server, data, initpath=None, parent=None)

Bases: MediaTag

Represents a single Style media tag. yes it's giving aesthetic tags 💖

Variables:

TAG (str) — 'Style'
FILTER (str) — 'style'

🧚 `plexapi.media.Subformat`

class plexapi.media.Subformat(server, data, initpath=None, parent=None)

Bases: MediaTag

Represents a single Subformat media tag.

Variables:

TAG (str) — 'Subformat'
FILTER (str) — 'subformat'

🍓 `plexapi.media.Tag`

class plexapi.media.Tag(server, data, initpath=None, parent=None)

Bases: MediaTag

Represents a single Tag media tag. the most main character of tags tbh 👑

Variables:

TAG (str) — 'Tag'
FILTER (str) — 'tag'

✨ `plexapi.media.Writer`

class plexapi.media.Writer(server, data, initpath=None, parent=None)

Bases: MediaTag

Represents a single Writer media tag — the person who wrote the thing, no cap ✍️

Variables:

TAG (str) — 'Writer'
FILTER (str) — 'writer'

🔥 `plexapi.media.Guid`

class plexapi.media.Guid(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Guid media tag — the lil ID card for external metadata sources 🪪

Variables:

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

🌈 `plexapi.media.Image`

class plexapi.media.Image(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Image media tag — pics pics pics 🖼️

Variables:

TAG (str) — 'Image'
alt (str) — The alt text for the image.
type (str) — The type of image (e.g. coverPoster, background, snapshot).
url (str) — The API URL (/library/metadata/<ratingKey>/thumb/<thumbid>).

⭐ `plexapi.media.Rating`

class plexapi.media.Rating(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Rating media tag. the numbers that decide if a movie ate or flopped 💀

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.

💜 `plexapi.media.Review`

class plexapi.media.Review(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Review for a Movie. somebody had opinions and honestly? same 🫶

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.

🎨 `plexapi.media.UltraBlurColors`

class plexapi.media.UltraBlurColors(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single UltraBlurColors media tag — the blurry color palette, iconic for backgrounds fr fr 🌈

Variables:

TAG (str) — 'UltraBlurColors'
bottomLeft (str) — The bottom left hex color.
bottomRight (str) — The bottom right hex color.
topLeft (str) — The top left hex color.
topRight (str) — The top right hex color.

👑 `plexapi.media.BaseResource`

class plexapi.media.BaseResource(server, data, initpath=None, parent=None)

Bases: PlexObject

The base class for all Art, Poster, and Theme objects — the mother of the aesthetic 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. so don't come for her if it's not a file path, bestie 😭

🖼️ `plexapi.media.Art`

class plexapi.media.Art(server, data, initpath=None, parent=None)

Bases: BaseResource

Represents a single Art object.

🦋 `plexapi.media.Logo`

class plexapi.media.Logo(server, data, initpath=None, parent=None)

Bases: BaseResource

Represents a single Logo object.

🌸 `plexapi.media.Poster`

class plexapi.media.Poster(server, data, initpath=None, parent=None)

Bases: BaseResource

Represents a single Poster object — the lil cover pic, lowkey the most important part of the whole vibe 🎀

✨ `plexapi.media.SquareArt`

class plexapi.media.SquareArt(server, data, initpath=None, parent=None)

Bases: BaseResource

Represents a single Square Art object. square! art! slay geometry 🧚

🎵 `plexapi.media.Theme`

class plexapi.media.Theme(server, data, initpath=None, parent=None)

Bases: BaseResource

Represents a single Theme object — the background music that lives in your head rent free 🎶

📖 `plexapi.media.Chapter`

class plexapi.media.Chapter(server, data, initpath=None, parent=None)

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.

⏱️ `plexapi.media.Marker`

class plexapi.media.Marker(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Marker media tag — yk, the skip-intro / credits markers that save your life 🙏

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.

🔒 `plexapi.media.Field`

class plexapi.media.Field(server, data, initpath=None, parent=None)

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.

🔎 `plexapi.media.SearchResult`

class plexapi.media.SearchResult(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single SearchResult. the "found it" moment ✨

Variables:

TAG (str) — 'SearchResult'

🤖 `plexapi.media.Agent`

class plexapi.media.Agent(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single Agent — not a spy, a metadata agent bestie 💀

Variables:

TAG (str) — 'Agent'

🧬 `plexapi.media.AgentMediaType`

class plexapi.media.AgentMediaType(server, data, initpath=None, parent=None)

Bases: Agent

Represents a single Agent MediaType.

Variables:

TAG (str) — 'MediaType'

📺 `plexapi.media.Availability`

class plexapi.media.Availability(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single online streaming service Availability — aka "where can I watch this and how much is it gonna cost me" 😭

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.

🔊 `plexapi.media.Level`

class plexapi.media.Level(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single loudness Level sample for an AudioStream.

Variables:

loudness (float) — Loudness level value

🧸 `plexapi.media.CommonSenseMedia`

class plexapi.media.CommonSenseMedia(server, data, initpath=None, parent=None)

Bases: PlexObject

Represents a single CommonSenseMedia media tag.

⚠️ Note: This object is only loaded with partial data from a Plex Media Server. Call reload() to load the full data from Plex Discover (Plex Pass required). don't forget the reload bestie, or you'll be staring at half the info wondering what went wrong 🙈

Variables:

TAG (str) — 'CommonSenseMedia'
ageRatings (List<AgeRating>) — List of AgeRating objects.
anyGood (str) — A brief description of the media's quality.
id (int) — The ID of the CommonSenseMedia tag.
key (str) — The unique key for the CommonSenseMedia tag.
oneLiner (str) — A brief description of the CommonSenseMedia tag.
parentalAdvisoryTopics (List<ParentalAdvisoryTopic>) — the list of ParentalAdvisoryTopic objects 📋
parentsNeedToKnow (str) — a short lil description of what parents should know about the media, yep 👀
talkingPoints (List<TalkingPoint>) — the list of TalkingPoint objects 💬

Example

from plexapi.server import PlexServer
plex = PlexServer('http://localhost:32400', token='xxxxxxxxxxxxxxxxxxxx')

# Retrieve the Common Sense Media info for a movie
movie = plex.library.section('Movies').get('Cars')
commonSenseMedia = movie.commonSenseMedia
ageRating = commonSenseMedia.ageRatings[0].age

# Load the Common Sense Media info from Plex Discover (Plex Pass required)
commonSenseMedia.reload()
parentalAdvisoryTopics = commonSenseMedia.parentalAdvisoryTopics
talkingPoints = commonSenseMedia.talkingPoints

`class plexapi.media.AgeRating(server, data, initpath=None, parent=None)`

Bases: PlexObject 🫶

Represents a single AgeRating for a Common Sense Media tag — it's giving one little age badge, that's the whole job.

Variables

TAG (str) — 'AgeRating' 🏷️
age (float) — the age rating (e.g. 13, 17) 🔢
ageGroup (str) — the age group for the rating (e.g. Little Kids, Teens, etc.) 👶🧑
rating (float) — the star rating (out of 5) ⭐
ratingCount (int) — how many ratings contributed to that star rating 🗳️
type (str) — the type of rating (official, adult, child) 🎀

`class plexapi.media.TalkingPoint(server, data, initpath=None, parent=None)`

Bases: PlexObject 🫶

Represents a single TalkingPoint for a Common Sense Media tag. One talking point, one vibe, periodt.

Variables

TAG (str) — 'TalkingPoint' 🏷️
tag (str) — the description of the talking point 💬

`class plexapi.media.ParentalAdvisoryTopic(server, data, initpath=None, parent=None)`

Bases: PlexObject 🫶

Represents a single ParentalAdvisoryTopic for a Common Sense Media tag — literally the "heads up bestie" object.

Variables

TAG (str) — 'ParentalAdvisoryTopic' 🏷️
id (str) — the ID of the topic (e.g. violence, language, etc.) 🆔
label (str) — the label for the topic (e.g. Violence & Scariness, Language, etc.) 🏷️
positive (bool) — whether the topic is considered positive ✨
rating (float) — the rating of the topic (out of 5) ⭐
tag (str) — the description of the parental advisory topic 📝

🦋 MIXINS PLEXAPI.MIXINS 🦋

PlexAPI Mixins Module — okay so this module contains mixins for Plex objects. Mixins are the little add-on superpowers, iykyk 💅

`class plexapi.mixins.AdvancedSettingsMixin`

Bases: object

Mixin for Plex objects that can have advanced settings ⚙️

preferences() — returns a list of Preferences objects.
preference(pref) — returns a Preferences object for the specified pref.
- Parameters
  - pref (str) — the id of the preference to return.
editAdvanced(**kwargs) — edit a Plex object's advanced settings.
defaultAdvanced() — edit all of a Plex object's advanced settings to default.

`class plexapi.mixins.AddedAtMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have an added at date 🗓️

editAddedAt(addedAt, locked=True) — 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.AudienceRatingMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have an audience rating 🍅

editAudienceRating(audienceRating, locked=True) — edit the audience rating.
- Parameters
  - audienceRating (float) — the new value.
  - locked (bool) — True (default) to lock the field, False to unlock the field 🔒

`class plexapi.mixins.CollectionMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have collections 🗂️

addCollection(collections, locked=True) — 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) — 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.ContentRatingMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a content rating 🔞

editContentRating(contentRating, locked=True) — 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.CountryMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have countries 🌍

addCountry(countries, locked=True) — 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) — 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.CriticRatingMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a critic rating 🍿

editCriticRating(criticRating, locked=True) — edit the critic rating.
- Parameters
  - criticRating (float) — the new value.
  - locked (bool) — True (default) to lock the field, False to unlock the field 🔒

`class plexapi.mixins.DirectorMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have directors 🎬

addDirector(directors, locked=True) — 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) — 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.EditionTitleMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have an edition title 📚

editEditionTitle(editionTitle, locked=True) — edit the edition title.

🎟️ heads up bestie: 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.EditFieldMixin`

Bases: object

Mixin for editing Plex object fields ✏️

editField(field, value, locked=True, **kwargs) — edit the field of a Plex object. All field editing methods can be chained together, fr fr. 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.EditTagsMixin`

Bases: object

Mixin for editing Plex object tags 🏷️

editTags(tag, items, locked=True, remove=False, **kwargs) — 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.GenreMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have genres 🎭

addGenre(genres, locked=True) — 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) — takes a genre tag (or a bunch) off the thing 💅

Parameters

genres (List<str> or List<MediaTag>) — the list of tags bestie, hand 'em over.
locked (bool) — True (default) locks the field, False unlocks it. locked = "don't touch my edits", unlocked = "free real estate".

🎀 class `plexapi.mixins.LabelMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have labels 🏷️ like, the object literally has a label field and this is how you feed it.

addLabel(labels, locked=True) — adds a label tag (or several) ✨

Parameters

labels (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeLabel(labels, locked=True) — yeets a label tag (or several) 🫶

Parameters

labels (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

🦋 class `plexapi.mixins.MoodMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have moods 🌈 the vibe field, basically. Very main character.

addMood(moods, locked=True) — adds a mood tag (or a whole moodboard of 'em) 💜

Parameters

moods (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeMood(moods, locked=True) — removes a mood tag (or several), vibe check complete 💀

Parameters

moods (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

🌸 class `plexapi.mixins.OriginallyAvailableMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have an originally available date 📅 the "it dropped on this day" field.

editOriginallyAvailable(originallyAvailable, locked=True) — edits the originally available date ✨

Parameters

originallyAvailable (str or datetime) — the new value, "YYYY-MM-DD" (str) or a datetime object. Note the quote marks in the original spec are <red>unbalanced — it says "YYYY-MM-DD (str) or datetime object — so yeah, that's how it is, don't come for me, I'm just the messenger 🙈
locked (bool) — True (default) locks the field, False unlocks it.

🧚 class `plexapi.mixins.OriginalTitleMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have an original title 🌍 like the title in its home language, before localization did its thing.

editOriginalTitle(originalTitle, locked=True) — edits the original title 💖

Parameters

originalTitle (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

📸 class `plexapi.mixins.PhotoCapturedTimeMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a captured time ⏰ the "when was this pic actually taken" field, for all my photo-library girlies.

editCapturedTime(capturedTime, locked=True) — edits the photo captured time 🕰️

Parameters

capturedTime (str or datetime) — the new value, "YYYY-MM-DD hh:mm:ss" (str) or a datetime object. Yes, with the time this time — hours, minutes AND seconds, she's thorough 💅
locked (bool) — True (default) locks the field, False unlocks it.

👑 class `plexapi.mixins.ProducerMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have producers 🎬 the money people, the ones who make it happen.

addProducer(producers, locked=True) — adds a producer tag (or several) 🔥

Parameters

producers (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeProducer(producers, locked=True) — removes a producer tag (or several) 😭

Parameters

producers (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

🎧 class `plexapi.mixins.SimilarArtistMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have similar artists 🫶 aka the "if you like this, you'll like that" crew.

addSimilarArtist(artists, locked=True) — adds a similar artist tag (or several) ⭐

Parameters

artists (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeSimilarArtist(artists, locked=True) — removes a similar artist tag (or several) 💔

Parameters

artists (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

🔤 class `plexapi.mixins.SortTitleMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a sort title 📚 the sneaky field that decides where it actually lands alphabetically, iykyk.

editSortTitle(sortTitle, locked=True) — edits the sort title 🌟

Parameters

sortTitle (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

🏢 class `plexapi.mixins.StudioMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a studio 🎥 the big-name house behind it.

editStudio(studio, locked=True) — edits the studio 🎬

Parameters

studio (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

💃 class `plexapi.mixins.StyleMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have styles ✨ the aesthetic tags, the ~vibes~ of it all.

addStyle(styles, locked=True) — adds a style tag (or several) 🎀

Parameters

styles (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeStyle(styles, locked=True) — removes a style tag (or several) 🦋

Parameters

styles (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

📝 class `plexapi.mixins.SummaryMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a summary 📖 the little blurb, the plot synopsis, the "what's this about" text.

editSummary(summary, locked=True) — edits the summary ✍️

Parameters

summary (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

💬 class `plexapi.mixins.TaglineMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a tagline 🎯 that one dramatic line on the poster, you know the one.

editTagline(tagline, locked=True) — edits the tagline 🌟

Parameters

tagline (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

🏷️ class `plexapi.mixins.TagMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have tags 🔖 the general-purpose tag field, for when the tag is just... a tag.

addTag(tags, locked=True) — adds a tag (or several) 💖

Parameters

tags (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

removeTag(tags, locked=True) — removes a tag (or several) 🙈

Parameters

tags (List<str> or List<MediaTag>) — the list of tags.
locked (bool) — True (default) locks the field, False unlocks it.

🌟 class `plexapi.mixins.TitleMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a title 👑 the name, the headline, the whole identity.

editTitle(title, locked=True) — edits the title ✨

Parameters

title (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

🎤 class `plexapi.mixins.TrackArtistMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a track artist 🎵 for when the artist on a specific track isn't the album artist (feature credits, collabs, the whole drama).

editTrackArtist(trackArtist, locked=True) — edits the track artist 🎶

Parameters

trackArtist (str) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

💿 class `plexapi.mixins.TrackDiscNumberMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a track disc number 📀 disc one, disc two, the deluxe edition situation.

editDiscNumber(discNumber, locked=True) — edits the track disc number 💽

Parameters

discNumber (int) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

🔢 class `plexapi.mixins.TrackNumberMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a track number 🎼 track 1, track 2, the order she was always meant to be in.

editTrackNumber(trackNumber, locked=True) — edits the track number 🎵

Parameters

trackNumber (int) — the new value.
locked (bool) — True (default) locks the field, False unlocks it.

⭐ class `plexapi.mixins.UserRatingMixin`

Bases: EditFieldMixin

Mixin for Plex objects that can have a user rating 💯 your personal score, not the critic score, your truth.

editUserRating(userRating, locked=True) — edits the user rating 🌟

Parameters

userRating (float) — the new value. Yeah, float — decimals allowed, she's precise 💅
locked (bool) — True (default) locks the field, False unlocks it.

✍️ class `plexapi.mixins.WriterMixin`

Bases: EditTagsMixin

Mixin for Plex objects that can have writers. ✍️ Like, the whole point of this one is tagging who wrote the thing, and you can lock it so Plex stops "helpfully" overwriting your choices.

addWriter(writers, locked=True) — adds a writer tag (or a whole bunch). Parameters:
- writers (List<str> or List<MediaTag>) — the list of tags, bestie.
- locked (bool) — True (the default) locks the field, False unlocks it. 🔒
removeWriter(writers, locked=True) — yeets a writer tag (or several). Same parameters:
- writers (List<str> or List<MediaTag>) — the list of tags.
- locked (bool) — True (default) locks the field, False unlocks the field.

✨ class plexapi.mixins.ExtrasMixin ✨

Bases: object

Mixin for Plex objects that can have extras (trailers, behind-the-scenes, all that bonus content 🎬).

extras() — returns a list of Extra objects. That's it, that's the whole vibe.

💫 class plexapi.mixins.HubsMixin 💫

Bases: object

Mixin for Plex objects that can have related hubs.

hubs() — returns a list of Hub objects.

👑 class plexapi.mixins.PlayedUnplayedMixin 👑

Bases: object

Mixin for Plex objects that can be marked played and unplayed. The "I definitely watched this already" mixin, iconic.

property isPlayed — returns True if this video is played.
markPlayed() — marks the Plex object as played. ✅
markUnplayed() — marks the Plex object as unplayed. 🙈
property isWatched — alias to self.isPlayed.
markWatched() — alias to markPlayed().
markUnwatched() — alias to markUnplayed().

⭐ class plexapi.mixins.RatingMixin ⭐

Bases: object

Mixin for Plex objects that can have user star ratings. Star ratings, we love her.

rate(rating=None) — rates the Plex object. Heads up: Plex ratings are displayed out of 5 stars (so a rating of 7.0 = 3.5 stars, math is math 💀). Parameters:
- rating (float, optional) — rating from 0 to 10. Leave it out to reset the rating.
- Raises BadRequest — if the rating is invalid. So, like, don't try rating=9000.

🖼️ class plexapi.mixins.ArtLockMixin 🖼️

Bases: object

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

lockArt() — locks the background artwork for a Plex object. 🔒
unlockArt() — unlocks the background artwork for a Plex object. 🔓

🎨 class plexapi.mixins.ArtMixin 🎨

Bases: ArtUrlMixin, ArtLockMixin

Mixin for Plex objects that can have background artwork — the big fanart energy.

arts() — returns a list of available Art objects.
uploadArt(url=None, filepath=None) — uploads 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 to the image to upload or file-like object.
setArt(art) — sets the background artwork for a Plex object. Parameters:
- art (Art) — the art object to select.
deleteArt() — deletes the art from a Plex object. Gone, girl. 💅

🦋 class plexapi.mixins.ArtUrlMixin 🦋

Bases: object

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

property artUrl — returns the art url for the Plex object.

🔐 class plexapi.mixins.LogoLockMixin 🔐

Bases: object

Mixin for Plex objects that can have a locked logo.

lockLogo() — locks the logo for a Plex object.
unlockLogo() — unlocks the logo for a Plex object.

🌟 class plexapi.mixins.LogoMixin 🌟

Bases: LogoUrlMixin, LogoLockMixin

Mixin for Plex objects that can have logos.

logos() — returns a list of available Logo objects.
uploadLogo(url=None, filepath=None) — uploads a logo from a url or filepath. Parameters:
- url (str) — the full URL to the image to upload.
- filepath (str) — the full file path to the image to upload or file-like object.
setLogo(logo) — sets the logo for a Plex object. Parameters:
- logo (Logo) — the logo object to select.
deleteLogo() — deletes the logo from a Plex object.

🌈 class plexapi.mixins.LogoUrlMixin 🌈

Bases: object

Mixin for Plex objects that can have a logo url.

property logo — returns the API path to the logo image.
property logoUrl — returns the logo url for the Plex object.

🎀 class plexapi.mixins.PosterLockMixin 🎀

Bases: object

Mixin for Plex objects that can have a locked poster.

lockPoster() — locks the poster for a Plex object.
unlockPoster() — unlocks the poster for a Plex object.

💖 class plexapi.mixins.PosterMixin 💖

Bases: PosterUrlMixin, PosterLockMixin

Mixin for Plex objects that can have posters. Main character of cover art, fr.

posters() — returns a list of available Poster objects.
uploadPoster(url=None, filepath=None) — uploads a poster from a url or filepath. Parameters:
- url (str) — the full URL to the image to upload.
- filepath (str) — the full file path to the image to upload or file-like object.
setPoster(poster) — sets the poster for a Plex object. Parameters:
- poster (Poster) — the poster object to select.
deletePoster() — deletes the poster from a Plex object.

🍓 class plexapi.mixins.PosterUrlMixin 🍓

Bases: object

Mixin for Plex objects that can have a poster url.

property thumbUrl — returns the thumb url for the Plex object.
property posterUrl — alias to self.thumbUrl.

🧚 class plexapi.mixins.SquareArtLockMixin 🧚

Bases: object

Mixin for Plex objects that can have a locked square art.

lockSquareArt() — locks the square art for a Plex object.
unlockSquareArt() — unlocks the square art for a Plex object.

💜 class plexapi.mixins.SquareArtMixin 💜

Bases: SquareArtUrlMixin, SquareArtLockMixin

Mixin for Plex objects that can have square art.

squareArts() — returns a list of available SquareArt objects.
uploadSquareArt(url=None, filepath=None) — uploads a square art from a url or filepath. Parameters:
- url (str) — the full URL to the image to upload.
- filepath (str) — the full file path to the image to upload or file-like object.
setSquareArt(squareArt) — sets the square art for a Plex object. Parameters:
- squareArt (SquareArt) — the square art object to select.
deleteSquareArt() — deletes the square art from a Plex object.

⬜ class plexapi.mixins.SquareArtUrlMixin ⬜

Bases: object

Mixin for Plex objects that can have a square art url.

property squareArt — returns the API path to the square art image.
property squareArtUrl — returns the square art url for the Plex object.

🎵 class plexapi.mixins.ThemeLockMixin 🎵

Bases: object

Mixin for Plex objects that can have a locked theme.

lockTheme() — locks the theme for a Plex object.
unlockTheme() — unlocks the theme for a Plex object.

🎶 class plexapi.mixins.ThemeMixin 🎶

Bases: ThemeUrlMixin, ThemeLockMixin

Mixin for Plex objects that can have themes. The little jingle that plays while you're browsing, iykyk.

themes() — returns a list of available Theme objects.
uploadTheme(url=None, filepath=None, timeout=None) — uploads a theme from url or filepath. 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).

⚠️ Warning: themes cannot be deleted using PlexAPI! Read that again. You can't delete them. No take-backs. 😭

setTheme(theme) — sets the theme for a Plex object.
- Raises NotImplementedError — themes cannot be set through the API. So sorry, bestie, that door is closed. 🚪
deleteTheme() — deletes the theme from a Plex object.

🎧 class plexapi.mixins.ThemeUrlMixin 🎧

Bases: object

Mixin for Plex objects that can have a theme url.

property themeUrl — returns the theme url for the Plex object.

🔎 class plexapi.mixins.SmartFilterMixin 🔎

Bases: object

Mixin for Plex objects that can have smart filters. (That's genuinely all the docs say — she's mysterious, she's lowkey.)

✂️ class plexapi.mixins.SplitMergeMixin ✂️

Bases: object

Mixin for Plex objects that can be split and merged.

split() — splits a duplicated Plex object into separate objects. Break it up, break it up. 💃
merge(ratingKeys) — merges other Plex objects into the current object. Parameters:
- ratingKeys (list) — a list of rating keys to merge.

🔄 class plexapi.mixins.UnmatchMatchMixin 🔄

Bases: object

Mixin for Plex objects that can be unmatched and matched.

unmatch() — unmatches the metadata match from the object. It's giving "who even are you". 🫠
matches(agent=None, title=None, year=None, language=None) — returns a 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 ✨ — copy these exactly, they're literally the cheat sheet:

1. video.matches()

2. video.matches(title="something", year=2020)

3. video.matches(title="something")

4. video.matches(year=2020)

5. video.matches(title="something", year="")

video.matches(title="", year=2020)
video.matches(title="", year="")

So here's the ✨vibe check✨ on what each of those actually does, bestie:

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) — okay so this one takes a match result and uses it to update your show metadata. Lowkey the glow-up button for your 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.WatchlistMixin`

Bases: object

Mixin for Plex objects that can be added to a user's watchlist. 🎀

onWatchlist(account=None) — 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) — 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) — 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) — 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.AlbumEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, CriticRatingMixin, OriginallyAvailableMixin, SortTitleMixin, StudioMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin, MoodMixin, StyleMixin

`class plexapi.mixins.ArtistEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, CriticRatingMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin, SimilarArtistMixin, StyleMixin

`class plexapi.mixins.CollectionEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, ContentRatingMixin, CriticRatingMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, LabelMixin

`class plexapi.mixins.EpisodeEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, ContentRatingMixin, CriticRatingMixin, OriginallyAvailableMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, DirectorMixin, LabelMixin, WriterMixin

`class plexapi.mixins.MovieEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, ContentRatingMixin, CriticRatingMixin, EditionTitleMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin, SummaryMixin, TaglineMixin, TitleMixin, UserRatingMixin, CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin

`class plexapi.mixins.PhotoEditMixins`

Bases: ArtLockMixin, PosterLockMixin, AddedAtMixin, PhotoCapturedTimeMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin, TagMixin

`class plexapi.mixins.PhotoalbumEditMixins`

Bases: ArtLockMixin, PosterLockMixin, AddedAtMixin, SortTitleMixin, SummaryMixin, TitleMixin, UserRatingMixin

`class plexapi.mixins.PlaylistEditMixins`

Bases: ArtLockMixin, PosterLockMixin, SortTitleMixin, SummaryMixin, TitleMixin

`class plexapi.mixins.SeasonEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, CriticRatingMixin, SummaryMixin, TitleMixin, UserRatingMixin, CollectionMixin, LabelMixin

`class plexapi.mixins.ShowEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, ContentRatingMixin, CriticRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin, SummaryMixin, TaglineMixin, TitleMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin

`class plexapi.mixins.TrackEditMixins`

Bases: ArtLockMixin, PosterLockMixin, ThemeLockMixin, AddedAtMixin, AudienceRatingMixin, CriticRatingMixin, TitleMixin, TrackArtistMixin, TrackNumberMixin, TrackDiscNumberMixin, UserRatingMixin, CollectionMixin, GenreMixin, LabelMixin, MoodMixin

`class plexapi.mixins.AlbumMixins`

Bases: SplitMergeMixin, UnmatchMatchMixin, RatingMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin, AlbumEditMixins

`class plexapi.mixins.ArtistMixins`

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

`class plexapi.mixins.ClipMixins`

Bases: ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, SquareArtUrlMixin

`class plexapi.mixins.CollectionMixins`

Bases: AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin, CollectionEditMixins

`class plexapi.mixins.EpisodeMixins`

Bases: ExtrasMixin, RatingMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin, EpisodeEditMixins

`class plexapi.mixins.MovieMixins`

`class plexapi.mixins.PhotoMixins`

Bases: RatingMixin, ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, SquareArtUrlMixin, PhotoEditMixins

`class plexapi.mixins.PhotoalbumMixins`

Bases: RatingMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, PhotoalbumEditMixins

`class plexapi.mixins.PlaylistMixins`

Bases: SmartFilterMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, PlaylistEditMixins

`class plexapi.mixins.SeasonMixins`

Bases: AdvancedSettingsMixin, ExtrasMixin, RatingMixin, ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin, SeasonEditMixins

`class plexapi.mixins.ShowMixins`

`class plexapi.mixins.TrackMixins`

Bases: ExtrasMixin, RatingMixin, ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, SquareArtUrlMixin, ThemeUrlMixin, TrackEditMixins

🌸 MYPLEX PLEXAPI.MYPLEX 🌸

class plexapi.myplex.MyPlexAccount(username=None, password=None, token=None, session=None, timeout=None, code=None, remember=True)

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 — literally the bestie who handles all the login admin for you 🫶

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) — tells you if login-with-email-only is turned on.
experimentalFeatures (bool) — whether the experimental features are enabled.
friendlyName (str) — your account's full name.
entitlements (List<str>) — the list of devices this account is allowed to use.
guest (bool) — is this account a Plex Home guest user?
hasPassword (bool) — does the account have a password?
home (bool) — is this account a Plex Home user?
homeAdmin (bool) — is this account the Plex Home admin?
homeSize (int) — how many accounts live in the Plex Home.
id (int) — the Plex account ID.
joinedAt (datetime) — the date the account joined Plex.
locale (str) — the account locale.
mailingListActive (bool) — are you 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) — does the account have 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) — does the account have a Plex Home PIN enabled?
rememberExpiresAt (datetime) — the date the token expires.
restricted (bool) — is this account a Plex Home managed user?
roles — (List<str>) a list of account roles. Plexpass membership is listed here, bestie.
scrobbleTypes (List<int>) — Unknown. Literally unknown, we don't gatekeep, we just don't know. 🙈
subscriptionActive (bool) — is the account's Plex Pass subscription active?
subscriptionDescription (str) — a description of the Plex Pass subscription.
subscriptionFeatures — (List<str>) the list of features allowed on your Plex Pass subscription.
subscriptionPaymentService (str) — the payment service used for your Plex Pass subscription.
subscriptionPlan (str) — the name of the Plex Pass subscription plan.
subscriptionStatus (str) — string representation of subscriptionActive.
subscriptionSubscribedAt (datetime) — the 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) — is two-factor authentication enabled?
username (str) — the account username.
uuid (str) — the account UUID.

💅 `signout()`

Signs you out of the Plex account. Heads up: this invalidates the authentication token, so like... don't do it mid-scroll and then act surprised. 😭

`authenticationToken` (property)

Returns the authentication token for the account. It's just an alias for authToken, no cap.

`ping()`

Pings the Plex.tv API. The cute part: this refreshes the authentication token so it doesn't expire on you. Self-care for your token, honestly. ✨

`device(name=None, clientId=None)`

Returns the MyPlexDevice that matches the name you specified.

Parameters:

name (str) — the name to match against.
clientId (str) — the clientIdentifier to match against.

`devices()`

Returns a list of all MyPlexDevice objects connected to the server. The whole squad. 🫶

`resource(name)`

Returns the MyPlexResource that matches the name specified.

Parameters:

name (str) — the name or machine identifier to match against.

`resources()`

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)`

Shares library content with the user you specify. Sharing is caring, bestie. 💖

Parameters:

user (MyPlexUser) — a MyPlexUser object, username, or email of the user to be added.
server (PlexServer) — a 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 the user to sync content.
allowCameraUpload (Bool) — set True to allow the user to upload photos.
allowChannels (Bool) — set True to allow the user to utilize installed channels.
filterMovies (Dict) — a dict containing the key 'contentRating' and/or 'label', each set to a list of values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
filterTelevision (Dict) — a dict containing the key 'contentRating' and/or 'label', each set to a list of values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
filterMusic (Dict) — a dict containing the 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)`

Shares library content with the specified user. (Yes, same description — the original says it too, and I'm not about to invent new lore. 🧚)

Parameters:

user (MyPlexUser) — a MyPlexUser object, username, or email of the user to be added.
server (PlexServer) — a 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 the user to sync content.
allowCameraUpload (Bool) — set True to allow the user to upload photos.
allowChannels (Bool) — set True to allow the user to utilize installed channels.
filterMovies (Dict) — a dict containing the key 'contentRating' and/or 'label', each set to a list of values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
filterTelevision (Dict) — a dict containing the key 'contentRating' and/or 'label', each set to a list of values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}
filterMusic (Dict) — a dict containing the 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)`

Shares library content with the specified user. Again, same one-liner as the original — I'm just the messenger. 🎀

Parameters:

user (MyPlexUser) — a MyPlexUser object, username, or email of the user to be added.
server (PlexServer) — a 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 the user to sync content.
allowCameraUpload (Bool) — set True to allow the user to upload photos.
allowChannels (Bool) — set True to allow the user to utilize installed channels.
filterMovies (Dict) — a dict containing the key 'contentRating' and/or 'label', each set to a list of values to be filtered. ex: {'contentRating':['G'], 'label':['foo']}

filterTelevision (Dict) — a dict with key 'contentRating' and/or 'label', each set to a list of values to filter out. like, {'contentRating':['G'], 'label':['foo']} ✨
- filterMusic (Dict) — a dict with the key 'label' set to a list of values to filter out. ex: {'label':['foo']} 🎀

`removeFriend(user)`

bestie removal protocol 💔 kicks the specified user out of your friends.

Parameters

user (MyPlexUser or str) — the MyPlexUser, username, or email of the user you're removing.

`removeHomeUser(user)`

same energy but for your home users — yeets the specified user out of your Plex Home. 🏠

Parameters

user (MyPlexUser or str) — the MyPlexUser, username, or email of the user to remove.

`switchHomeUser(user, pin=None)`

gives you back a whole new MyPlexAccount object that's logged in as the given home user. it's giving "who am i today" main character energy 🦋

Parameters

user (MyPlexUser or str) — the MyPlexUser, username, or email of the home user you wanna switch to.
pin (str) — the PIN for that home user (required if the home user has a PIN set, no skipping 💅).

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)`

sets a brand new Plex Home PIN on the account 🔐

Parameters

newPin (str) — the new PIN you want to set.
currentPin (str) — the account's current PIN (required if you're changing the PIN, like, you gotta prove it's you).

`removePin(currentPin)`

deletes the Plex Home PIN off the account entirely, poof 🫧

Parameters

currentPin (str) — the account's current PIN (required to remove the PIN).

`setManagedUserPin(user, newPin)`

sets a fresh Plex Home PIN for a managed home user. heads up: this has to be done from the Plex Home admin account, no sneaking around it 👑

Parameters

user (MyPlexUser or str) — the MyPlexUser or username of the managed home user.
newPin (str) — the new PIN to set for that managed home user.

`removeManagedUserPin(user)`

strips the Plex Home PIN off a managed home user. again, admin account only, i don't make the rules 🫶

Parameters

user (MyPlexUser or str) — the MyPlexUser or username of the managed home user.

`acceptInvite(user)`

accepts a pending friend invite from the specified user. say yes bestie 💖

Parameters

user (MyPlexInvite or str) — the MyPlexInvite, username, or email of the friend invite you're accepting.

`cancelInvite(user)`

cancels a pending invite for the specified user. (the manpage literally spells it "firend" and honestly? firend. 💀 iconic typo, keeping the vibe.)

Parameters

user (MyPlexInvite or str) — the 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)`

the glow-up method for a user's share settings ✨ tweak their access without removing them.

Parameters

user (MyPlexUser) — the MyPlexUser object, username, or email of the user being updated.
server (PlexServer) — a PlexServer object, or a machineIdentifier, containing the library sections you're sharing.
sections (List<LibrarySection>) — a list of LibrarySection objects, or names, to be shared (default None). sections must be defined in order to update shared libraries, ok?
removeSections (Bool) — set True to remove all shares. this supersedes sections. ⚠️
allowSync (Bool) — set True to let the user sync content.
allowCameraUpload (Bool) — set True to let the user upload photos 📸
allowChannels (Bool) — set True to let the user utilise installed channels.
filterMovies (Dict) — a dict with key 'contentRating' and/or 'label', each set to a list of values to filter. ex: {'contentRating':['G'], 'label':['foo']}
filterTelevision (Dict) — a dict with key 'contentRating' and/or 'label', each set to a list of values to filter. ex: {'contentRating':['G'], 'label':['foo']}
filterMusic (Dict) — a dict with key 'label' set to a list of values to filter. ex: {'label':['foo']}

`user(username)`

hands you the MyPlexUser matching that username or email 🔍

Parameters

username (str) — username, email, or id of the user to return.

`users()`

returns a list of all the MyPlexUser objects connected to your account. the whole friend group, assembled 🌈

`pendingInvite(username, includeSent=True, includeReceived=True)`

returns the MyPlexInvite matching that 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)`

returns a list of every MyPlexInvite object connected to your account. 📮 note: this includes all pending invites sent from your account and received to it.

Parameters

includeSent (bool) — True to include sent invites.
includeReceived (bool) — True to include received invites.

`optOut(playback=None, library=None)`

opt in or out of sharing stuff with plex. 👀 see: https://www.plex.tv/about/privacy-legal/

`syncItems(client=None, clientId=None)`

returns an instance of SyncList for the 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 are provided, the client wins 🏆 if neither is provided, clientId gets set to the current client's identifier.

`sync(sync_item, client=None, clientId=None)`

adds the specified sync item for the client. ngl it's always easier to use the methods defined directly on the media objects, e.g. sync(), sync() 💅

Parameters

client (MyPlexDevice) — a client you need to add the SyncItem to.
clientId (str) — an identifier of a client you need to add the SyncItem to.
sync_item (SyncItem) — a prepared SyncItem object with all fields set.

if both client and clientId are provided, the client wins 🏆 if neither is provided, clientId gets set to the current client's identifier.

Returns

an instance of the created syncItem. 🎉

Return type

SyncItem

Raises

BadRequest — when a client with the provided clientId wasn't found. 😭
BadRequest — the provided client doesn't provide a sync-target.

`claimToken()`

returns a str — a fresh "claim-token" 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)`

gets the 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) — minimum datetime to return results from.

`onlineMediaSources()`

returns a list of the user account's Online Media Sources settings — AccountOptOut 📺

`videoOnDemand()`

returns a list of VOD Hub items — Hub 🎬

`tidal()`

returns a list of tidal Hub items — Hub 🎵

`watchlist(filter=None, sort=None, libtype=None, maxresults=None, **kwargs)`

returns a list of Movie and Show items sitting in the user's watchlist 🍿 note: the objects returned come 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) — the format is field:dir. Fields you can sort by: watchlistedAt (Added At), titleSort (Title), originallyAvailableAt (Release Date), or rating (Critic Rating). And dir can be asc or desc. That's it, that's the whole vibe 💅
libtype (str, optional) — 'movie' or 'show' if you only want movies or only want shows, otherwise it gives you everything.
maxresults (int, optional) — caps it at the number of results you specify, bestie. No more, no less.
**kwargs (dict) — extra custom filters you wanna slap onto the search results. Go off, customize.

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)`

Returns True if the item is on the user's watchlist. simple as that, a little yes/no moment ✨

Parameters

item (Movie or Show) — the item you're checking, bestie. Is it on the watchlist or not, we gotta know.

`addToWatchlist(items)`

Adds media items to the user's watchlist. Get them on the list! 🎀

Parameters

items (List) — a list of Movie or Show objects to be added to the watchlist.

Raises BadRequest — when you try to add invalid or existing media to the watchlist. yeah, no double-adding, the list is not having it 🙈

`removeFromWatchlist(items)`

Removes media items from the user's watchlist. Bye bestie 👋

Parameters

items (List) — a list of Movie or Show objects to be added to the watchlist. (yes, that's what the docs say, we're removing but it still says "added" — iconic typo behavior, we keep it 💀)

Raises BadRequest — when you try to remove invalid or non-existing media to the watchlist.

`userState(item)`

Returns a UserState object for the specified item. Little state machine moment.

Parameters

item (Movie or Show) — the item to return the user state for.

`isPlayed(item)`

Returns True if the item is played on Discover.

okay so the original docstring for this one is a whole sphinx situation, and we are not editing it because the details matter. Here it is verbatim: :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.: — so: item can be a Movie, Show, Season or Episode object from searchDiscover(), and it can also be a result from the Plex Movie or Plex TV Series agent. 🫶

`markPlayed(item)`

Marks the Plex object as played on Discover.

same sphinx situation, verbatim: :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.: — so again, item can be a Movie, Show, Season or Episode from searchDiscover(), or a result from the Plex Movie or Plex TV Series agent.

`markUnplayed(item)`

Marks the Plex object as unplayed on Discover. undoing the deed 😭

verbatim once more: :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.: — item is a Movie, Show, Season or Episode from searchDiscover(), or a result from the Plex Movie or Plex TV Series agent.

`searchDiscover(query, limit=30, libtype=None, providers='discover')`

Searches for movies and TV shows in Discover. Returns a list of Movie and Show objects. this is the main character of the api ngl 🔥

Parameters

query (str) — the search query, obviously. what are we looking for queen.
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.
providers (str, optional) — 'discover' for default behavior, or 'discover,PLEXAVOD' to also include the Plex ad-supported video service, or 'discover,PLEXAVOD,PLEXTVOD' to also include the Plex video rental service. options on options, we love to see it 💜

property `viewStateSync`

Returns True or False if syncing of watch state and ratings is enabled or disabled, respectively, for the account. Binary queen.

`enableViewStateSync()`

Enables syncing of watch state and ratings for the account. turn it on ✨

`disableViewStateSync()`

Disables syncing of watch state and ratings for the account. turn it off 💀

`link(pin)`

Links a device to the account using a pin code.

Parameters

pin (str) — the 4 digit link pin code. four digits, that's it, don't overthink it 🎀

`publicIP()`

Returns your public IP address. hi bestie, you're at this address apparently 🌈

`geoip(ip_address)`

Returns a GeoLocation object with geolocation information for an IP address using Plex's GeoIP database.

Parameters

ip_address (str) — the IP address to look up.

🦋 `class plexapi.myplex.MyPlexUser(server, data, initpath=None, parent=None)`

Bases: PlexObject

This object represents non-signed in users, like friends and linked accounts. NOTE: do not confuse this 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) — the 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) — the 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 user's avatar.
title (str) — seems to be an alias for username.
username (str) — the user's username.

`server(name)`

Returns the MyPlexServerShare that matches the name specified.

Parameters

name (str) — name of the server to return.

`history(maxresults=None, mindate=None)`

Get all Play History for a user in all shared servers.

verbatim docstring time: :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime — so maxresults is an optional int capping the results, and mindate is a datetime for the minimum point to return results from. 🫶

🌸 `class plexapi.myplex.MyPlexInvite(server, data, initpath=None, parent=None)`

Bases: PlexObject

This object represents pending friend invites. the "omg did they accept yet" energy 😭

Variables

TAG (str) — 'Invite'
createdAt (datetime) — datetime the user was invited.
email (str) — the 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) — the 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 user's avatar.
username (str) — the user's username.

🧚 `class plexapi.myplex.Section(server, data, initpath=None, parent=None)`

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 (there's a soft hyphen situation in the original, ignore it, the URL is the URL 💅)

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)`

Get all Play History for a user for this section in this shared server.

verbatim again: :param maxresults: Only return the specified number of results (optional). :type maxresults: int :param mindate: Min datetime to return results from. :type mindate: datetime — maxresults optional int, mindate datetime for the earliest result you want back. ✨

⭐ `class plexapi.myplex.MyPlexServerShare(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single user's server reference. Used for library sharing. this is the "which server do they even have access to" object 👑

Variables

id (int) — id for this share
serverId (str) — what id plex uses for this.
machineIdentifier (str) — the server's machineIdentifier
name (str) — the server's 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)`

Returns the Section that matches the name specified.

Parameters

name (str) — name of the section to return.

`sections()`

Returns a list of all Section objects shared with this user. all of them. every single one. periodt 💜

🌸 `history(maxresults=9999999, mindate=None)`

okay so literally all the Play History for a user on this shared server, in one go 💖

maxresults (int, optional) — cap it at this many results if you don't want the whole entire archive. it's optional, king.
mindate (datetime) — the minimum datetime to return results from. like, "only the stuff after this moment pls".

🧚 class `plexapi.myplex.MyPlexResource(server, data, initpath=None, parent=None)`

Bases: PlexObject

so this one is giving main character energy for everything connected to your Plex server that can actually serve up content — Plex Media Servers, iPhones, Android clients, the whole squad 🫶. the raw xml for all this is literally sitting 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) — the unique ID for this resource
connections (list) — a list of ResourceConnection objects for this resource
createdAt (datetime) — timestamp of when 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 of when this resource last connected
name (str) — the 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) — the 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)`

returns a sorted list of the available connection addresses for this resource, bestie. often times there's more than one address specified for a server or client, and the default behaviour 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.

ngl the locations and schemes params are just sitting there in the signature — the docs don't say a word about them, so I'm not gonna make anything up 🙈

👑 `connect(ssl=None, timeout=None, locations=None, schemes=None)`

returns a brand new PlexServer or PlexClient object. it 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 handed right back to you 🌸

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 it's unable to connect to any addresses for this resource. 😭

🎀 class `plexapi.myplex.ResourceConnection(server, data, initpath=None, parent=None)`

Bases: PlexObject

represents a Resource Connection object found within the MyPlexResource objects. tiny but iconic.

🦋 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 🙈 (their spelling, not mine, i'm just the messenger)

⭐ class `plexapi.myplex.MyPlexDevice(server, data, initpath=None, parent=None)`

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 lives 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)`

returns a new PlexClient or PlexServer. sometimes there's more than one address specified for a server or client, and after trying to connect to all available addresses for this client — assuming at least one connection was successful — the PlexClient object is built and returned 💖

Raises NotFound — when it's unable to connect to any addresses for this device.

💀 `delete()`

removes this device from your account. bye bestie 👋

🌈 `syncItems()`

returns an instance of SyncList for the current device.

Raises BadRequest — when the device doesn't provides sync-target. (yep, they wrote it like that, and honestly? same energy 😭)

🧸 class `plexapi.myplex.MyPlexPinLogin(session=None, requestTimeout=None, headers=None, oauth=False)`

Bases: object

this is the MyPlex PIN login class — it supports getting a token for authenticating the client, and it provides an access token so you can create a MyPlexAccount instance ✨. the login can be done using the four character PIN which the user must enter at https://plex.tv/link, or using Plex OAuth.

this helper class supports a polling, threaded and callback approach — pick your fighter:

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 Plex.
requestTimeout (int, optional) — timeout in seconds on initial connect to plex.tv (default config.TIMEOUT).
headers (dict, optional) — a dict of X-Plex headers to send with requests.
oauth (bool, optional) — True to use Plex OAuth instead of PIN login.

🎀 Variables

PINS (str) — 'https://plex.tv/api/v2/pins'
POLLINTERVAL (int) — 1
pin (str) — four character PIN to use for the login at https://plex.tv/link
finished (bool) — whether the pin login has finished or not
expired (bool) — whether the pin login has expired or not
token (str) — the token you get back after login. That's the whole prize, bestie 🎀

Example

from plexapi.myplex import MyPlexAccount, MyPlexPinLogin

pinlogin = MyPlexPinLogin(oauth=True)
pinlogin.run()
print(f'Login to Plex at the following url:\n{pinlogin.oauthUrl()}')
pinlogin.waitForLogin()
token = pinlogin.token

account = MyPlexAccount(token=token)

property pin — returns the four-character PIN used for linking a device at https://plex.tv/link. It's literally an activation code, iykyk 💅

oauthUrl(forwardUrl=None) — returns the Plex OAuth url for login.

forwardUrl (str, optional) — the url to redirect the client to after login.

run(callback=None, timeout=120) — kicks off the thread that monitors the PIN login state. Set it and forget it kinda energy ✨

callback (Callable[str], optional) — callback called with the received authentication token.
timeout (int, optional) — timeout in seconds to wait for user login. Default 120 seconds.

Raises

RuntimeError — if the thread is already running. One thread at a time, we're not doing chaos here 😭
RuntimeError — if the PIN login for the current PIN has expired.

waitForLogin() — waits for the PIN login to succeed or expire. It will simply sit there until something happens, and honestly? Same.

Returns: True if the PIN login succeeded or False otherwise.

Return type: bool

stop() — stops the thread monitoring the PIN login state. Bye bestie 👋

checkLogin() — returns True if the PIN login has succeeded.

👑 `class plexapi.myplex.MyPlexJWTLogin(session=None, requestTimeout=None, headers=None, oauth=False, token=None, jwtToken=None, keypair=(None, None), scopes=None)`

Bases: object

The MyPlex JWT login class — it gets you a JWT for authenticating the client and hands over an access token so you can build a MyPlexAccount instance. Lowkey the glow-up of the login world 🌈

Login can happen two ways: with the four-character PIN the user types in at https://plex.tv/link, or with Plex OAuth. This class can also refresh or verify a JWT you already have. Versatile queen 👑

See: https://developer.plex.tv/pms/#section/API-Info/Authenticating-with-Plex

Heads up bestie: using this class requires the PyJWT with the cryptography packages installed — that's pyjwt[crypto]. No package, no party 🙈

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 Plex.
requestTimeout (int, optional) — timeout in seconds on initial connect to plex.tv (default config.TIMEOUT).
headers (dict, optional) — a dict of X-Plex headers to send with requests.
oauth (bool, optional) — True to use Plex OAuth instead of PIN login.
token (str, optional) — Plex token, only required to register the device initially if not using OAuth.
jwtToken (str, optional) — existing Plex JWT to verify or refresh.
keypair (tuple[str|bytes], optional) — a tuple of the full file paths (str) to the ED25519 private and public key pair, or the raw keys themselves (bytes), to use for signing the JWT. Use generateKeypair() to generate a new keypair if not provided.
scope (list[str], optional) — list of scopes to request in the new token. Default is all available scopes.

Variables

PINS (str) — 'https://plex.tv/api/v2/pins'
AUTH (str) — 'https://clients.plex.tv/api/v2/auth'
POLLINTERVAL (int) — 1
SCOPES (list) — list of all available scopes to request for the JWT.
pin (str) — four character PIN to use for the login at https://plex.tv/link.
finished (bool) — whether the JWT login has finished or not.
expired (bool) — whether the JWT login has expired or not.
jwtToken (str) — the Plex JWT received after login or refreshing.
decodedJWT (dict) — the decoded Plex JWT payload.

Example

from plexapi.myplex import MyPlexAccount, MyPlexJWTLogin

# Method 1: Generate a new Plex JWT using Plex OAuth
jwtlogin = MyPlexJWTLogin(
    oauth=True,
    scopes=['username', 'email', 'friendly_name']
)
jwtlogin.generateKeypair(keyfiles=('private.key', 'public.key'))
jwtlogin.run()
print(f'Login to Plex at the following url:\n{jwtlogin.oauthUrl()}')
jwtlogin.waitForLogin()
jwtToken = jwtlogin.jwtToken

account = MyPlexAccount(token=jwtToken)

# Method 2: Generate a new Plex JWT using an existing Plex token and keypair
jwtlogin = MyPlexJWTLogin(
    token='2ffLuB84dqLswk9skLos',
    keypair=('private.key', 'public.key'),
    scopes=['username', 'email', 'friendly_name']
)
jwtlogin.registerDevice()
jwtToken = jwtlogin.refreshJWT()

account = MyPlexAccount(token=jwtToken)

# Refresh an existing Plex JWT
jwtlogin = MyPlexJWTLogin(
    jwtToken=jwtToken,
    keypair=('private.key', 'public.key'),
    scopes=['username', 'email', 'friendly_name']
)
if not jwtlogin.verifyJWT():
    jwtToken = jwtlogin.refreshJWT()

account = MyPlexAccount(token=jwtToken)

generateKeypair(keyfiles=(None, None), overwrite=False) — generates a fresh ED25519 private/public keypair for signing the JWT and saves them to files. Requires the cryptography package to be installed. New keys who dis 🔑

keyfiles (tuple[str]) — a tuple of the full file paths to write the private and public keypair to.
overwrite (bool) — set to True to overwrite existing keypair files. Default is False.

Raises FileExistsError — when keypair files already exist and overwrite is False.

decodePlexJWT(verify_signature=True) — returns the decoded Plex JWT with optional signature verification using the Plex public JWK.

verify_signature (bool) — whether to verify the JWT signature and required claims. Defaults to True. Set to False to skip signature verification and required-claim enforcement.

property decodedJWT — returns the decoded Plex JWT with signature verification and required-claim enforcement. The trustworthy version ✨

registerDevice() — registers the device with Plex using the provided token and private/public keypair. This must be done once if OAuth was not used, before the Plex JWT can be refreshed. One and done, no cap 💅

Raises BadRequest — when token or keypair is missing.

refreshJWT() — refreshes the Plex JWT using the existing private/public keypair. Glow-up era 🌸

Returns: the new Plex JWT.

Return type: str

Raises

BadRequest — when keypair is missing.
BadRequest — when the newly obtained JWT cannot be verified.

verifyJWT(refreshWithinDays=1) — verifies the existing Plex JWT is valid and not expiring within the specified number of days. A vibe check for your token 🔥

refreshWithinDays (int) — number of days before expiration to consider the JWT invalid and in need of refresh. Default is 1 day.

property pin — returns the four character PIN used for linking a device at https://plex.tv/link.

oauthUrl(forwardUrl=None) — returns the Plex OAuth url for login.

forwardUrl (str, optional) — the url to redirect the client to after login.

run(callback=None, timeout=120) — starts the thread which monitors the PIN login state.

callback (Callable[str], optional) — callback called with the received authentication token.
timeout (int, optional) — timeout in seconds to wait for user login. Default 120 seconds.

Raises

RuntimeError — if the thread is already running.
RuntimeError — if the PIN login for the current PIN has expired.

waitForLogin() — waits for the user login to succeed or expire.

Returns: True if the user login succeeded or False otherwise.

Return type: bool

stop() — stops the thread monitoring the user login state. Thread said ✌️

checkLogin() — returns True if the user login has succeeded. ✅ periodt, login success is the vibe check.

`class plexapi.myplex.AccountOptOut(server, data, initpath=None, parent=None)`

Bases: PlexObject

okay so this one represents a single AccountOptOut — literally the https://plex.tv/api/v2/user/{userUUID}/settings/opt_outs situation. 💅

Variables

TAG (str) — optOut
key (str) — Online Media Source key
value (str) — Online Media Source opt_in, opt_out, or opt_out_managed
optIn() — sets the Online Media Source to "Enabled". ✨
optOut() — sets the Online Media Source to "Disabled". 🫶
optOutManaged() — sets the Online Media Source to "Disabled for Managed Users". 🎀

Raises BadRequest — when trying to opt out music. 😭 not the music, bestie.

`class plexapi.myplex.UserState(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single UserState. It's giving "watch history but make it a whole object" energy. 👑

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)`

Bases: PlexObject

Represents a single IP address geolocation. lowkey iconic for knowing where the vibes are coming from. 🌍

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)`

Bases: PlexPartialObject, PhotoalbumMixins

okay bestie, this one is literally a single Photoalbum — aka a whole collection of photos, one cute lil' bundle 💖.

Variables

TAG (str) — 'Directory'
TYPE (str) — 'photo'
addedAt (datetime) — when the photo album got added to the library, timestamped and everything.
art (str) — URL to the artwork image, shaped like /library/metadata/<ratingKey>/art/<artid>.
composite (str) — URL to the composite image, /library/metadata/<ratingKey>/composite/<compositeid>
fields (List<Field>) — a list of field objects, slay.
guid (str) — the Plex GUID for the photo album, like local://229674.
images (List<Image>) — list of image objects 🖼️
index (sting) — Plex index number for the photo album. (yes, the original says "sting", we don't ask questions, we just report it 💅)
key (str) — API URL, /library/metadata/<ratingkey>.
lastRatedAt (datetime) — when the photo album was last rated.
librarySectionID (int) — LibrarySection ID.
librarySectionKey (str) — LibrarySection key.
librarySectionTitle (str) — LibrarySection title.
listType (str) — hardcoded as 'photo' (super useful for search filters, iykyk).
ratingKey (int) — the unique key identifying this photo album.
summary (str) — summary of the photoalbum.
thumb (str) — URL to the thumbnail image, /library/metadata/<ratingKey>/thumb/<thumbid>.
title (str) — name of the photo album. (Trip to Disney World)
titleSort (str) — the title to use when sorting (defaults to title).
type (str) — 'photo'
updatedAt (datetime) — when the photo album was updated.
userRating (float) — rating of the photo album (0.0 - 10.0), which equals (0 stars - 5 stars) ⭐

`album(title)`

Returns the Photoalbum that matches the title you pass in.

Parameters

title (str) — Title of the photo album to return.

`albums(**kwargs)`

Returns a list of Photoalbum objects that live inside the album.

`photo(title)`

Returns the Photo that matches the title you asked for.

Parameters

title (str) — Title of the photo to return.

`photos(**kwargs)`

Returns a list of Photo objects in the album 🫶

`clip(title)`

Returns the Clip that matches the specified title.

Parameters

title (str) — Title of the clip to return.

`clips(**kwargs)`

Returns a list of Clip objects in the album.

`get(title)`

Alias to photo(). Same energy, shorter name ✨

`download(savepath=None, keep_original_name=False, subfolders=False)`

Downloads all the photos and clips from the photo album. See download() for the details, bestie.

Parameters

savepath (str) — defaults to the current working directory.
keep_original_name (bool) — True to keep the original filename, otherwise a friendlier filename gets generated.
subfolders (bool) — True to separate photos/clips into 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)`

Bases: PlexPartialObject, Playable, PhotoMixins

This is one single Photo. One. Iconic 🎀

Variables

TAG (str) — 'Photo'
TYPE (str) — 'photo'
addedAt (datetime) — when the photo was added to the library.
createdAtAccuracy (str) — Unknown (local).
createdAtTZOffset (int) — Unknown (-25200).
fields (List<Field>) — list of field objects.
guid (str) — the Plex GUID for the photo, com.plexapp.agents.none://231714?lang=xn.
images (List<Image>) — list of image objects.
index (sting) — Plex index number for the photo. (again with the "sting", we stay faithful 💀)
key (str) — API URL, /library/metadata/<ratingkey>.
lastRatedAt (datetime) — when 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) — when the photo was added to Plex.
parentGuid (str) — the 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 the 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 the thumbnail image, /library/metadata/<ratingKey>/thumb/<thumbid>.
title (str) — name of the photo.
titleSort (str) — the title to use when sorting (defaults to title).
type (str) — 'photo'
updatedAt (datetime) — when the photo was updated.
userRating (float) — rating of the photo (0.0 - 10.0), equaling (0 stars - 5 stars).
year (int) — the year the photo was taken 📅

`photoalbum()`

Returns the photo's Photoalbum. like, who's your parent, bestie?

`section()`

Returns the LibrarySection the item belongs to.

property `locations`

heads up: this does not exist in the plex xml response — it's added on so there's a common interface for getting 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)`

Adds the current photo as a sync item for a specified device. See sync() for possible exceptions (yes, possible exceptions, be aware 👀).

Parameters

resolution (str) — maximum allowed resolution for synchronized photos, see the 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 it's empty the value gets generated from the metadata of the current photo.

Returns

an instance of the created syncItem.

Return type

SyncItem

property `metadataDirectory`

Returns the Plex Media Server data directory where the metadata is stored.

`class plexapi.photo.PhotoSession(server, data, initpath=None, parent=None)`

Bases: PlexSession, Photo

Represents a single Photo session, loaded from sessions(). main character energy, currently playing 🦋

🎵 PLAYLIST PLEXAPI.PLAYLIST

`class plexapi.playlist.Playlist(server, data, initpath=None, parent=None)`

Bases: PlexPartialObject, Playable, PlaylistMixins

Represents a single Playlist. your queue, your rules, periodt 💅

Variables

TAG (str) — 'Playlist'
TYPE (str) — 'playlist'
addedAt (datetime) — when the playlist was added to the server.
allowSync (bool) — True if you allow syncing playlists.
composite (str) — URL to the 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) — the 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) — the lil summary blurb of the playlist ✨
title (str) — the playlist's name, bestie 💖
titleSort (str) — the title to use when sorting (defaults to title)
type (str) — literally just 'playlist'
updatedAt (datetime) — the datetime the playlist was last updated 🕐

property `thumb` 🎀

Alias to self.composite.

property `metadataType`

Returns the type of metadata in the playlist — so like movie, track, or photo. iykyk 💅

property `isVideo`

Returns True if this is a video playlist. simple as that 🦋

property `isAudio`

Returns True if this is an audio playlist 🎧

property `isPhoto`

Returns True if this is a photo playlist 📸

`filters()`

Returns the search filter dict for the smart playlist. and like, the whole point — that filter dict gets passed right back into search() to get your list of items back out. no cap ✨

`section()`

Returns the LibrarySection this smart playlist belongs to.

Raises

plexapi.exceptions.BadRequest — when you're trying to get the section for a regular playlist 🙈
plexapi.exceptions.Unsupported — when it literally cannot determine the library section 😭

`item(title)`

Returns the item in the playlist that matches the title you specified 🎯

Parameters

title (str) — Title of the item to return.

Raises plexapi.exceptions.NotFound — when that item is not found in the playlist 💀

`items()`

Returns a list of all the items in the playlist. all of them. periodt 👑

`get(title)`

Alias to item(). same thing, shorter name, we love convenience 🫶

`addItems(items)`

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 you try to add items to a smart playlist (rude, but like, not allowed)

`removeItems(items)`

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)`

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 the item you said after, does not exist in the playlist 💀

`updateFilters(limit=None, sort=None, filters=None, **kwargs)`

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 you try to update filters for a regular playlist 🙅‍♀️

`delete()`

Delete the playlist. gone. poof. 💨

classmethod `create(server, title, section=None, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, m3ufilepath=None, **kwargs)`

Create a playlist 🎀 main character energy fr fr

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 bestie: this will overwrite any playlist previously created from the same m3u file. like, actually overwrite it 💀

**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 an m3u file into a non-music library.
plexapi.exceptions.BadRequest — when it failed to import the m3u file.

Returns — A new instance of the created Playlist. 🎉

Return type — Playlist

`copyToUser(user)`

Copy the playlist to another user account 🫶 sharing is caring

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)`

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 the sync module. Used only when the playlist contains video.
photoResolution (str) — maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in the module sync. Used only when the playlist contains photos.
audioBitrate (int) — maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync. Used only when the 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 the playlist is not allowed to sync.
Unsupported — when the playlist content is unsupported.

Returns — A new instance of the created sync item.

Return type — SyncItem

property `metadataDirectory`

Returns the Plex Media Server data directory where the metadata is stored 📁 iconic

🎀 PLAYQUEUE PLEXAPI.PLAYQUEUE 🎀

class plexapi.playqueue.PlayQueue(server, data, initpath=None, parent=None)

Bases: PlexObject

Okay so this class is your little remote control for a PlayQueue 🎛️ — literally the thing controlling what plays next. Slay.

✨ Variables ✨

TAG (str) — fr it's just 'PlayQueue'
TYPE (str) — and this one's 'playqueue'
identifier (str) — com.plexapp.plugins.library, no cap
items (list) — the actual list of Playable or Playlist baddies
mediaTagPrefix (str) — Fx /system/bundle/media/flags/ 🏷️
mediaTagVersion (int) — Fx 1485957738
playQueueID (int) — the ID of the PlayQueue, iconic
playQueueLastAddedItemID (int) — this one defines where the "Up Next" region starts. It stays empty unless the PlayQueue gets modified after creation, iykyk 👀
playQueueSelectedItemID (int) — the queue item ID of whatever's currently selected
playQueueSelectedItemOffset (int) — the offset of the selected item in the PlayQueue, counted from the very beginning of the queue
playQueueSelectedMetadataItemID (int) — ID of the currently selected item, and yes it matches ratingKey
playQueueShuffled (bool) — True if shuffled, periodt
playQueueSourceURI (str) — the original URI that was used to create the PlayQueue
playQueueTotalCount (int) — how many items are in the PlayQueue
playQueueVersion (int) — version of the PlayQueue, and it increments every single time a change is made to the PlayQueue 💅
selectedItem (Playable) — media object for the currently selected item
_server (PlexServer) — the PlexServer associated with the PlayQueue
size (int) — alias for playQueueTotalCount, cute

💖 getQueueItem(item) 💖

Accepts a media item and returns a similar object from this PlayQueue. So useful for looking up playQueueItemIDs using items you got from the Library. Obsessed honestly.

🌸 classmethod get(server, playQueueID, own=False, center=None, window=50, includeBefore=True, includeAfter=True) 🌸

Retrieve an existing PlayQueue by identifier. Grab it, bestie.

Parameters

server (PlexServer) — the server you're connected to
playQueueID (int) — identifier of an existing PlayQueue
own (bool, optional) — if the server should transfer ownership
center (int, optional) — the playQueueItemID of the center of the window. Heads up: this 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. And if False it does not include the center either
includeAfter (bool, optional) — include items after the center, defaults True. Same deal, False means the center is out too

🦋 classmethod create(server, items, startItem=None, shuffle=0, repeat=0, includeChapters=1, includeRelated=1, continuous=0) 🦋

Create and return a brand new PlayQueue. Main character energy 🫶

Parameters

server (PlexServer) — the server you're connected to
items (PlexPartialObject) — a media item, or a whole 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 (and yes, the docs literally say "shuffled" for this one too, that's just what it says, no notes 💀)
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, literally nothing 🌈

⭐ classmethod fromStationKey(server, key) ⭐

Create and return a new PlayQueue.

This is a convenience method to create a PlayQueue for radio stations when you only have the key string available. Ngl this one's a lifesaver.

Parameters

server (PlexServer) — the server you're 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) 🍓

Append the provided item to the "Up Next" section of the PlayQueue. Important vibe check: items can only be added to the section immediately following the currently playing item.

Parameters

item (Playable or Playlist) — a single media item or a Playlist
playNext (bool, optional) — if True, add this item to the front of the "Up Next" section. If False, the item gets appended to the end of the "Up Next" section. This 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) 🧚

Moves an item to the beginning of the PlayQueue. If after is provided, the item gets placed immediately after the specified item instead.

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) 💜

Remove an item from the PlayQueue. Bye bestie 👋

Parameters

item (Playable) — an existing item in the PlayQueue to move
refresh (bool, optional) — refresh the PlayQueue from the server before updating

🌈 clear() 🌈

Remove all items from the PlayQueue. Total reset, we love a clean slate.

🔥 refresh() 🔥

Refresh the PlayQueue from the Plex server.

👑 SERVER PLEXAPI.SERVER 👑

class plexapi.server.PlexServer(baseurl=None, token=None, session=None, timeout=None)

Bases: PlexObject

Okay so THIS is the main entry point to interacting with a Plex server, the icon itself ✨. It lets you list connected clients, browse your library sections, and perform actions such as emptying trash. And if you don't know the auth token required to access your Plex server — or you simply want to access your server with your username and password — you can also create a PlexServer instance from MyPlexAccount. Convenient fr.

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, the cute one
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) — the list of features the server owner is allowed to use 💅 this one's lowkey tied to your PlexPass subscription. The 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, bestie, the list keeps growing).
photoAutoTag (bool) — True if photo auto-tagging is turned on 🎀
platform (str) — the platform your server is hosted on (ex: Linux)
platformVersion (str) — the version of that platform (ex: '6.1 (Build 7601)', '4.4.0-59-generic').
pluginHost (bool) — unknown 🙈 literally nobody documented this one
readOnlyLibraries (bool) — unknown 🙈
requestParametersInCookie (bool) — unknown 🙈
streamingBrainVersion (bool) — the current Streaming Brain version 🧠✨
sync (bool) — True if syncing to a device is enabled.
transcoderActiveVideoSessions (int) — how many video transcoding sessions are active rn 🔥
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 (the docs say bool, and we simply do not question the docs 💀).
transcoderVideoQualities (bool) — list of video qualities.
transcoderVideoResolutions (bool) — list of video resolutions.
updatedAt (int) — the datetime the server was updated.
updater (bool) — unknown 🙈
version (str) — the current Plex version (ex: 1.3.2.3112-1751929)
voiceSearch (bool) — True if voice search is enabled. (is this Google Voice search? genuinely asking 🫶)
_baseurl (str) — the HTTP address of the client.
_token (str) — the token used to access this client.
_session (obj) — the 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()`

Returns the Plex server identity 🪪

`account()`

Returns the Account object this server belongs to.

`claim(account)`

Claim the Plex server using a MyPlexAccount. Heads up bestie: 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()`

Unclaim the Plex server. This will remove the server from your MyPlexAccount 💔

property `activities`

Returns all current PMS activities.

`agents(mediaType=None)`

Returns a list of Agent objects this server has available.

`createToken(type='delegation', scope='all')`

Create a temp access token for the server 🎟️

`switchUser(user, session=None, timeout=None)`

Returns a new PlexServer object logged in as the given username. 📝 Note: only the admin account can switch to other users — that's the whole vibe check right there 👑

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()`

Returns a list of SystemAccount objects this server contains.

`systemAccount(accountID)`

Returns the SystemAccount object for the specified account ID.

Parameters

accountID (int) — the SystemAccount ID.

`systemDevices()`

Returns a list of SystemDevice objects this server contains 📱

`systemDevice(deviceID)`

Returns the SystemDevice object for the specified device ID.

Parameters

deviceID (int) — the SystemDevice ID.

`myPlexAccount()`

Returns a MyPlexAccount object using the same token to access this server. 🚨 Real talk: if you are not the owner of this PlexServer you're likely to receive an authentication error calling this.

`browse(path=None, includeFiles=True)`

Browse the system file path using the Plex API. Returns a 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)`

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)`

Returns True if the Plex server can browse the given path.

Parameters

path (Path or str) — full path to browse.

`clients()`

Returns a list of all PlexClient objects connected to server 📺

`client(name)`

Returns the PlexClient that matches the specified name or machine identifier.

Parameters

name (str) — name or machine identifier 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)`

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)

Okay so this one creates and returns a brand new Playlist for you 💖 it's literally the "make me a playlist" button and it ate.

💫 Parameters

title (str) — the title of the playlist. name your baby.
section (LibrarySection, str) — smart playlists and m3u import only bestie, this is the library section you wanna create the playlist in.
items (List) — regular playlists only! a list of Audio, Video, or Photo objects to be added to the playlist.
smart (bool) — True to create a smart playlist. Default False (so regular by default, no cap).
limit (int) — smart playlists only, limits 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. so like, heads up 💀
**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.

So yeah, four separate ways to get a BadRequest and honestly? respect.

🫶 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"
)

look at that, three whole vibes: regular, smart, and the m3u import one 🎀

createPlayQueue(item, **kwargs)

Creates and returns a new PlayQueue. the queue is queuing, your honor 🌸

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)

Download databases. literally just grabbing the 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)

Download server logs. same energy as above but it's the logs 🫶

Parameters

savepath (str) — defaults to current working dir.
unpack (bool) — unpack the zip file.
showstatus (bool) — display a progressbar.

butlerTasks()

Return a list of ButlerTask objects. yes the butler has tasks, he's booked and busy 👑

runButlerTask(task)

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. so like, don't sit there staring at your terminal waiting for it bestie, go look at Plex Web 😭

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)

Returns a Release object containing release info if an update is available or None if no update is available. vibe check on your version ✨

Parameters

force (bool) — force server to check for new releases
download (bool) — download if a update is available.

isLatest()

Returns True if the installed version of Plex Media Server is the latest. slay, you're up to date 💅

canInstallUpdate()

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.) sorry docker girlies, it's giving manual labour 😔

installUpdate()

Automatically install the newest version of Plex Media Server. go go go 🔥

history(maxresults=None, mindate=None, ratingKey=None,
accountID=None, librarySectionID=None)

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. fr fr listen to this advice, it'll save you so much time 🕐

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)

Returns a list of all Playlist objects on the server. all of them. every single one 🎀

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)

Returns the Playlist that matches the specified title. just the one, the main character 👑

Parameters

title (str) — title of the playlist to return.

Raises

NotFound — unable to find playlist. she's not here bestie 😭

optimizedItems(removeAll=None)

Returns list of all Optimized objects connected to server. optimized and thriving ✨

conversions(pause=None)

Returns list of all Conversion objects connected to server. the conversions are converting, periodt 💫

currentBackgroundProcess()

Returns list of all TranscodeJob objects running or paused on server. look at them go, all in the background, lowkey iconic 🌈

query(key, method=None, headers=None, params=None, timeout=None,
**kwargs)

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. the backbone of the whole operation honestly, no cap 🫶

search(query, mediatype=None, limit=None, sectionId=None)

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. the way this search actually understands context?? obsessed 😭💖

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) — how many results you want per Hub, bestie. Cap it.
sectionId (int, optional) — the section ID (a.k.a. the key) of the library you wanna search inside. iykyk 🎀

`continueWatching()`

Returns a list of every item chillin' in the Continue Watching hub. Your "bestie I swear I'll finish this show" queue, but as objects. 💅

`sessions()`

Returns a list of all the active session media objects — like, everything that's currently playing. The live tea. ☕

`transcodeSessions()`

Returns a list of all the active TranscodeSession objects. Yes, all of them. Every single one. 🔥

`startAlertListener(callback=None, callbackError=None)`

Opens a websocket connection to the Plex Server so you can optionally get notifications. These are usually messages from Plex about media scans, plus updates to Transcode Sessions that are currently running. Returns a brand-new AlertListener object. ✨

Note: websocket-client has to be installed for this feature to work. No cap.

>> pip install websocket-client

Parameters

callback (func) — the callback function to call whenever a message comes in.
callbackError (func) — the callback function to call when things go sideways (errors).

Raises Unsupported — because websocket-client isn't installed, bestie. 😭

`transcodeImage(imageUrl, height, width, opacity=None, saturation=None, blur=None, background=None, blendColor=None, minSize=True, upscale=True, imageFormat=None)`

Returns the URL for a transcoded image. Glow-up for your pics, literally. 🦋

Parameters

imageUrl (str) — the URL to the image (like the one returned by thumbUrl() or artUrl()). Heads up: the URL can be an online image.
height (int) — the height to transcode the image to.
width (int) — the width to transcode the image to.
opacity (int, optional) — changes the opacity of the image (0 to 100).
saturation (int, optional) — changes 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 applied behind the opacity (e.g. '000000').
blendColor (str, optional) — the hex colour to blend the image with (e.g. '000000').
minSize (bool, optional) — maintain the smallest dimension. Default True.
upscale (bool, optional) — upscale the image if it's required. Default True.
imageFormat (str, optional) — 'jpeg' (default) or 'png'.

`url(key, includeToken=None)`

Builds a URL string with the proper token argument. The token gets appended to the URL if either includeToken is True or CONFIG.log.show_secrets is 'true'. Sneaky token behavior, honestly. 🙈

`refreshSynclist()`

Forces PMS to download a fresh SyncList from Plex.tv. Out with the old, in with the new. 🧚

`refreshContent()`

Forces PMS to refresh content for the SyncLists it already knows about.

`refreshSync()`

Calls refreshSynclist() and refreshContent() — exactly what the Plex Web UI does when you click 'refresh'. Main character behavior. 👑

`bandwidth(timespan=None, **kwargs)`

Returns a list of StatisticsBandwidth objects containing the Plex server dashboard bandwidth data. Your data usage, but make it fashion. 📊

Parameters

timespan (str, optional) — the timespan used to bin the bandwidth data. Default is seconds. Available timespans: seconds, hours, days, weeks, months.
**kwargs (dict, optional) — any of the available filters you can slap onto the bandwidth data. The time frame (at) and bytes can also be filtered with less-than or greater-than (check the examples below, bestie).
- accountID (int) — the SystemAccount ID to filter by.
- 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, ngl) (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 by.
- lan (bool) — True to only retrieve local bandwidth, False to only retrieve remote bandwidth. Default returns all local and remote bandwidth.

Raises BadRequest — when you apply an invalid timespan or an unknown filter. Rude, but fair. 💀

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()`

Returns a list of StatisticsResources objects holding the Plex server dashboard resources data. The receipts. 🧾

`getWebURL(base=None, playlistTab=None)`

Returns the Plex Web URL for the server. Cute link moment. 🔗

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)`

Bases: PlexObject

Contains the locally cached MyPlex account information. Lowkey, the properties it provides don't match the MyPlexAccount object very well. The reasoning (per the docs) is that this exists because access to myplex isn't required to get basic plex info — and honestly I can't imagine this object is terribly useful unless you needed this info while offline. Fr fr. 🌸

Parameters

server (PlexServer) — the PlexServer this account is connected to (optional).
data (ElementTree) — the response from PlexServer used to build this object (optional).

Variables

mappingError (str) — Unknown. 🤷‍♀️
mappingErrorMessage (str) — Unknown. Again. 💀
mappingState (str) — Unknown. We stay guessing.
privateAddress (str) — the local IP address of the Plex server.
privatePort (str) — the local port of the Plex server.
publicAddress (str) — the public IP address of the Plex server.
publicPort (str) — the public port of the Plex server.
signInState (str) — the signin state for this account (ex: ok).
subscriptionActive (str) — True if the account subscription is active.
subscriptionFeatures (str) — the list of features the server allows 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) — the Plex account username (like user@example.com).

`class plexapi.server.Activity(server, data, initpath=None, parent=None)`

Bases: PlexObject

A currently running activity on the PlexServer. It's giving "something is happening rn". 🔥

`class plexapi.server.Release(server, data, initpath=None, parent=None)`

Bases: PlexObject

(The docs don't say more than that, bestie — it's a PlexObject subclass and that's the whole vibe.) 🎀

`class plexapi.server.SystemAccount(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single system account. One account, one icon. 👑

Variables

TAG (str) — 'Account'.
autoSelectAudio (bool) — True or False depending on whether the account has automatic audio language enabled.
Identity — ngl every server's gotta know who it is 💅
ButlerTask — the little scheduled chores your server does while you sleep 🧹
StatisticsResources — the actual numbers, the receipts 📊

🫶 `class plexapi.server.SystemDevice(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single system device. One device, one entry, iconic behavior.

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)`

Bases: PlexObject

Represents a single statistics bandwidth data. Numbers go brrr 📈

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()`

Returns the SystemAccount associated with the bandwidth data.

`device()`

Returns the SystemDevice associated with the bandwidth data.

🎀 `class plexapi.server.StatisticsResources(server, data, initpath=None, parent=None)`

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).

ok bestie those four descriptions are exactly what the docs say, i'm just the messenger, don't @ me 🙈

🧹 `class plexapi.server.ButlerTask(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a single scheduled butler task. The server's unpaid intern, fr.

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)`

Bases: PlexObject

Represents a server identity. Main character energy, obviously.

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 ✨

The glow-up zone 💖 literally where you tweak your server's whole personality.

🌸 `class plexapi.settings.Settings(server, data, initpath=None)`

Bases: PlexObject

Container class for all settings. Allows getting and setting PlexServer settings.

Variables:

key (str) — '/:/prefs'

`all()`

Returns a list of all Setting objects available.

`get(id)`

Return the Setting object with the specified id.

`groups()`

Returns a dict of lists for all Setting objects grouped by setting group.

`group(group)`

Return a list of all Setting objects in the specified group.

Parameters:

group (str) — Group to return all settings.

`save()`

Save any outstanding setting changes to the PlexServer. This performs a full reload() of Settings after complete.

⚠️ bestie, listen: changes are NOT real until you call save(). They just vibe in memory. 😭

🎀 `class plexapi.settings.Setting(server, data, initpath=None, parent=None)`

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)`

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.

🫶 yes it's worded exactly like that in the original. say it with me: save(). that's the whole assignment.

`toUrl()`

Helper for urls

💜 `class plexapi.settings.Preferences(server, data, initpath=None, parent=None)`

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.

💀 bestie do NOT post your token logs. that is a whole security situation. pls.

`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) — the DLNA default protocol info, bestie. This is the protocol info string the DLNA server drops in its GetProtocolInfo responses. 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: (yes, that's the whole thing, don't @ me 💀)
dlnaDescriptionIcons (text) — the DLNA server description icons, aka the icons the DLNA server offers up when devices come asking for the server description. default: png,jpeg;260x260,120x120,48x48
dlnaDeviceDiscoveryInterval (int) — DLNA media renderer discovery interval. It's the number of seconds between DLNA media renderer discovery requests. default: 60
dlnaEnabled (bool) — turn the DLNA server on. This is what lets the server stream media out 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. Enables 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. Heads up: 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. Also Plex Pass only 👑
cinemaTrailersPrerollID (text) — Cinema Trailers pre-roll video. Copy and paste the video's detail page URL into this field, that's literally it 🫶
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 gets 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 the folder that changed gets scanned.
fSEventLibraryUpdatesEnabled (bool) — update my library automatically. Your library gets 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. Real talk: Linux systems limit the maximum number of watched directories, so this may cause problems with large music libraries 🫠

🌈 Network Settings 🌈

allowedNetworks (text) — list of IP addresses and networks that are allowed without auth. A 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. The domain name to be published to plex.tv using your mapped port; it 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 lets the media server discover other servers and players on the local network. default: True
lanNetworksBandwidth (text) — LAN Networks. A 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 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 won't be able to connect at all. default: 1; choices: 0:Required|1:Preferred|2:Disabled
wanPerUserStreamCount (int) — remote streams allowed per user. The 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. Trade-offs, bestie.
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. Limits 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. The quality profile used by the transcoder. choices: 0:Automatic|1:Prefer higher speed encoding|2:Prefer higher quality encoding|3:Make my CPU hurt (yes that's a real option name, iconic 💀)
transcoderTempDirectory (text) — transcoder temporary directory. The 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. Slay, no port forwarding required ✨
transcoderCanOnlyRemuxVideo (bool) — the transcoder can only remux video.
transcoderVideoResolutionLimit (text) — maximum video output resolution for the transcoder. default: 0x0
wanPerStreamMaxUploadRate (int) — this is the cap on the bitrate of a remote stream coming out of this here server, iykyk. Limit remote stream bitrate. Set the maximum bitrate of a remote stream from this server. 🦋 The choices are literally: 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, measured in kilobits per second. Pop in 0 and congrats, you have set no limit bestie 💅

🫣 Undocumented Settings 🫣

Okay so these ones are, like, the mysterious cool kids — no descriptions given, just vibes and types. Not me listing them all anyway because nothing gets skipped on my watch 👑

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, timeout=None)

Bases: PlexClient

Bestie. This is the class for interacting with a Sonos speaker via the Plex API, and it's giving main character energy fr fr 🌈 The way it works? This class makes requests to an external Plex API, which then forwards the Sonos-specific commands right back to your Plex server & Sonos speakers. So it's a whole round trip. Iconic, honestly.

Heads up before you get excited: 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. No remote access = no slay 😭

More details on the Sonos integration are available here: https://support.plex.tv/articles/218237558-requirements-for-using-plex-for-sonos/

And like, the Sonos API emulates the Plex player control API closely, so if you know one you lowkey know the other: 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)` 🎵

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 🌈

Okay bestie, so 💖 Mobile Sync — you can literally work with it on other devices right away, no gatekeeping. But if you want your app to be a sync-target (like, the thing items get synced to), you gotta init some variables first. Slay:

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

The way you have to fake platform/device/model is lowkey not optional — transcoding profiles are hardcoded in Plex, that's just the vibe 😭. And yeah, you obviously also gotta explicitly say your app supports sync-target. No cap.

🦋 class `plexapi.sync.SyncItem(server, data, initpath=None, clientIdentifier=None)`

Bases: PlexObject

Represents a single sync item, for the specified server and client ✨. Like, when you're in the UI and you say sync "this" to "that", congrats bestie, you basically just created 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. Every time you modify the item (e.g. by changing amount if media to sync) a new version gets 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()`

Returns MyPlexResource with server of current item.

🫶 `getMedia()`

Returns list of Playable which belong to this sync item.

🫶 `markDownloaded(media)`

Mark the file as downloaded — and 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()`

Removes current SyncItem. Byeee 💀

🦋 class `plexapi.sync.SyncList(server, data, initpath=None, parent=None)`

Bases: PlexObject

Represents a Mobile Sync state, specific for a single client — and within one SyncList you may see items from different servers 👀. Chaotic but iconic.

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)`

Bases: object

Represents the current status of a specific SyncItem. Vibe check for your sync, basically ✨

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)`

Bases: object

Transcoding settings used for all media within a SyncItem 🔥. Look at all those defaults, we love a well-configured queen.

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)`

Returns a MediaSettings object, based on the 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)`

Returns a MediaSettings object, based on the 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)`

Returns a MediaSettings object, based on the 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)`

Bases: object

The policy of syncing the media — like, how many items to sync and whether to 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)`

Creates a Policy object for the provided options and automatically sets the proper scope value ✨. It's giving effortless.

Parameters

limit (int) — limit items by count.
unwatched (bool) — if True then watched items wouldn't be synced.

Returns Policy.

okay that's the sync tea for now, but we're literally not done — more parts coming bestie, don't go anywhere 💖

plexapi.utils.downloadSessionImages(server, filename=None, height=150, width=150, opacity=100, saturation=100) — the lil helper bestie that grabs a bif image (or a thumb.url) straight off plex.server.sessions. 🖼️ Params:
- server — the server you're pulling from.
- 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}}, ... and the return type is literally documented as {'hellowlol' — yes really, that's what it says, no cap. 💀

plexapi.utils.download(url, token, filename=None, savepath=None, session=None, chunksize=4096, unpack=False, mocked=False, showstatus=False) — helper to download a thumb, videofile or other media item. Returns the local path to the downloaded file. 📥
- 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) — lil helper that tries to get a MyPlexAccount instance by checking these locations for a username and password. Super useful for building user-friendly command line tools, fr. It goes:
1. command-line options (opts).
2. environment variables and config.ini.
3. prompt on the command line.
plexapi.utils.createMyPlexDevice(headers=None, account=None, timeout=10) — helper to create a new MyPlexDevice. Returns a new MyPlexDevice instance. 🎀
- headers (dict) — provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required, or one will be generated if not provided.
- 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) — helper for Plex OAuth login. Returns a new MyPlexAccount instance. 🔐
- headers (dict) — provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required, or one will be generated if not provided.
- forwardUrl (str, optional) — the url to redirect the client to after login.
- timeout (int, optional) — timeout in seconds to wait for user login. Default 120 seconds.
plexapi.utils.plexJWTAuth(headers=None, forwardUrl=None, timeout=120, keypair=(None, None), scopes=None) — helper for Plex JWT authentication using Plex OAuth. Returns a new MyPlexAccount instance. 🪪
- headers (dict, optional) — provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required, or one will be generated if not provided.
- forwardUrl (str, optional) — the url to redirect the client to after login.
- timeout (int, optional) — timeout in seconds to wait for user login. Default 120 seconds.
- keypair (tuple, optional) — a tuple of the ED25519 (privateKey, publicKey) to use for signing the JWT. If not provided, a new keypair will be generated and saved to 'private.key' and 'public.key'. 🗝️
- scopes (list[str], optional) — list of scopes to request in the JWT.
plexapi.utils.choose(msg, items, attr) — command line helper that displays a list of choices and asks the user to pick one of the options. Multiple choice but make it cute. 💅
plexapi.utils.getAgentIdentifier(section, agent) — returns the full agent identifier from a short identifier, name, or confirms a full identifier. 🔎
plexapi.utils.iterXMLBFS(root, tag=None) — iterates through an XML tree using a breadth-first search. If tag is specified, it only returns nodes with that tag. 🌳
plexapi.utils.toJson(obj, **kwargs) — converts an object to a JSON string. ✨
- obj (object) — the object to convert.
- **kwargs (dict) — keyword arguments to pass to json.dumps().
plexapi.utils.sha1hash(guid) — returns the SHA1 hash of a guid. 🔢
plexapi.utils.parseXMLString(s: str) — parses an XML string and returns an ElementTree object. 📜

🎬 VIDEO PLEXAPI.VIDEO 🎬

class plexapi.video.Video(server, data, initpath=None, parent=None)
- Bases: PlexPartialObject, PlayedUnplayedMixin

Okay so this is THE base class for all video objects — and when we say all, we mean Movie, Show, Season, Episode, and Clip. Every one of them is a Video girlie at heart. 👑🎥

Variables ⭐ (the list rolls on into what's next, stay tuned bestie)

addedAt (datetime) — when the item got added to the library 💖
art (str) — URL to the artwork image (/library/metadata/<ratingKey>/art/<artid>).
artBlurHash (str) — the BlurHash string for that artwork image ✨
fields (List<Field>) — a list of field objects.
guid (str) — the Plex GUID for the movie, show, season, episode, or clip (plex://movie/5d776b59ad5437001f79c6f8).
images (List<Image>) — a list of image objects 🎀
key (str) — the API URL (/library/metadata/<ratingkey>).
lastRatedAt (datetime) — when the item was last rated.
lastViewedAt (datetime) — when the item was last played.
librarySectionID (int) — the LibrarySection ID.
librarySectionKey (str) — the LibrarySection key.
librarySectionTitle (str) — the LibrarySection title.
listType (str) — hardcoded as 'video' (super handy for search filters, iykyk).
ratingKey (int) — the unique key that identifies the item 👑
summary (str) — the summary of the movie, show, season, episode, or clip.
thumb (str) — URL to the thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).
thumbBlurHash (str) — the BlurHash string for the thumbnail image.
title (str) — the name of the movie, show, season, episode, or clip.
titleSort (str) — the title to use when sorting (defaults to title).
type (str) — 'movie', 'show', 'season', 'episode', or 'clip'.
updatedAt (datetime) — when the item was last updated.
userRating (float) — the rating of the item (0.0 - 10.0), which equals (0 stars - 5 stars) ⭐
viewCount (int) — how many times the item was played.

`url(part)`

Gives you back the full URL for whatever you're pointing at — usually you're using it to grab one specific image 🖼️

`augmentation()`

Returns a list of Hub objects. Augmentation hands you back hub items tied to online media sources, like Tidal Music's "Track from {item}" or "Soundtrack of {item}". Heads up: Plex Pass and a linked Tidal account are required, no cap 💅

`uploadSubtitles(filepath)`

Uploads a subtitle file for the video.

Parameters

filepath (str) — path to the subtitle file.

`searchSubtitles(language='en', hearingImpaired=0, forced=0)`

Searches 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

A list of SubtitleStream objects.

Return type

List<SubtitleStream>

`downloadSubtitles(subtitleStream)`

Downloads on-demand subtitles for the video. See → https://support.plex.tv/articles/subtitle-search/.

Note: this method is asynchronous and returns immediately before the subtitles are fully downloaded. So don't go looking for the file the second you call it, bestie 😭

Parameters

subtitleStream (SubtitleStream) — subtitle object returned from searchSubtitles().

`removeSubtitles(subtitleStream=None, streamID=None, streamTitle=None)`

Removes an uploaded or downloaded subtitle from the video.

Note: if the subtitle file lives inside the video directory, it will be deleted. Files outside of the video directory are not affected. Embedded subtitles cannot be removed — periodt 🙈

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)`

Makes 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 a 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 the VIDEO_QUALITY_* values defined in the sync module. Only used if target is custom.
locationID (int or Location, optional) — defaults to -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 optimize 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)`

Adds the current video (movie, tv-show, season or episode) as a sync item for a specified device. See sync() for possible exceptions.

Parameters

videoQuality (int) — idx of quality of the video, one of the VIDEO_QUALITY_* values defined in the 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 the metadata of the current media.

Returns

an instance of the created syncItem.

Return type

SyncItem

🌈 class `plexapi.video.Movie(server, data, initpath=None, parent=None)`

Bases: Video, Playable, MovieMixins

Represents a single Movie 🎬 main character energy fr fr

Variables

TAG (str) — 'Video'
TYPE (str) — 'movie'
audienceRating (float) — audience rating (usually from Rotten Tomatoes).
audienceRatingImage (str) — key to audience rating image (rottentomatoes://image.rating.spilled).
chapters (List<Chapter>) — list of chapter objects.
chapterSource (str) — chapter source (agent; media; mixed).
collections (List<Collection>) — list of collection objects.
commonSenseMedia (CommonSenseMedia) — Common Sense Media object.
contentRating (str) — content rating (PG-13; NR; TV-G)
countries (List<Country>) — list of country objects.
directors (List<Director>) — list of director objects.
duration (int) — duration of the movie in milliseconds.
editionTitle (str) — the edition title of the movie (e.g. Director's Cut, Extended Edition, etc.).
enableCreditsMarkerGeneration (int) — setting that indicates if credits markers detection is enabled. (-1 = Library default, 0 = Disabled)
genres (List<Genre>) — list of genre objects.
guids (List<Guid>) — list of guid objects.
labels (List<Label>) — the list of label objects, bestie 💅
languageOverride (str) — setting that says whether a language overrides the metadata (eg. en-CA, None = Library default).
markers (List<Marker>) — list of marker objects ✨
media (List<Media>) — list of media objects, the actual files basically.
originallyAvailableAt (datetime) — the datetime the movie was released 🎀
originalTitle (str) — the original title, and yes it's often the foreign one (転々; 엽기적인 그녀) — iconic honestly.
primaryExtraKey (str) — Primary extra key (/library/metadata/66351)
producers (List<Producer>) — list of producers objects.
rating (float) — movie critic rating (7.9; 9.8; 8.1).
ratingImage (str) — key to the critic rating image (rottentomatoes://image.rating.rotten).
ratings (List<Rating>) — list of rating objects ⭐
roles (List<Role>) — list of role objects.
slug (str) — the clean watch.plex.tv URL identifier for the movie 🦋
similar (List<Similar>) — list of Similar objects.
sourceURI (str) — Remote server URI (server://<machineIdentifier>/com.plexapp.plugins.library) (remote playlist item only).
studio (str) — studio that created the movie (Di Bonaventura Pictures; 21 Laps Entertainment).
tagline (str) — movie tag line (Back 2 Work; Who says men can't change?).
theme (str) — URL to the theme resource (/library/metadata/<ratingkey>/theme/<themeid>).
ultraBlurColors (UltraBlurColors) — ultra blur color object, the aesthetic one 🌈
useOriginalTitle (int) — setting that indicates if the original title is used for the movie (-1 = Library default, 0 = No, 1 = Yes).
viewOffset (int) — view offset in milliseconds.
writers (List<Writer>) — list of writers objects ✍️
year (int) — year the movie was released.

🌸 property `actors`

Alias to self.roles. same thing, different name, we love a double identity moment 💅

🌸 property `locations`

Ok so real talk: this does not exist in the plex xml response, it's added here so there's a common interface for getting the locations of the movie. no cap.

Returns

List<str> of file paths where the movie is found on disk. 🍓

🌸 property `hasCreditsMarker`

Returns True if the movie has a credits marker. periodt.

🌸 property `hasVoiceActivity`

Returns True if any of the media has voice activity analyzed 👑

🌸 property `hasPreviewThumbnails`

Returns True if any of the media parts has generated preview (BIF) thumbnails 🔥

🌸 `reviews()`

Returns a list of Review objects.

🌸 `editions()`

Returns a list of Movie objects for other editions of the same movie. yes, the director's cut girlies stay fed 🎬

🌸 `removeFromContinueWatching()`

Remove the movie from continue watching. bye bestie 👋

🌸 property `metadataDirectory`

Returns the Plex Media Server data directory where the metadata is stored. 🗂️

👑 class `plexapi.video.Show(server, data, initpath=None, parent=None)`

Bases: Video, ShowMixins

Represents a single Show (including all seasons and episodes). the whole era, not just one ep 💜

Variables

TAG (str) — 'Directory'
TYPE (str) — 'show'
audienceRating (float) — audience rating (TMDB or TVDB).
audienceRatingImage (str) — key to the audience rating image (tmdb://image.rating).
audioLanguage (str) — setting that indicates the preferred audio language.
autoDeletionItemPolicyUnwatchedLibrary (int) — setting that indicates the number of unplayed episodes to keep for the show (0 = All episodes, 5 = 5 latest episodes, 3 = 3 latest episodes, 1 = 1 latest episode, -3 = Episodes added in the past 3 days, -7 = Episodes added in the past 7 days, -30 = Episodes added in the past 30 days).
autoDeletionItemPolicyWatchedLibrary (int) — setting that indicates if episodes are deleted after being watched for the show (0 = Never, 1 = After a day, 7 = After a week, 100 = On next refresh).
childCount (int) — number of seasons (including Specials) in the show.
collections (List<Collection>) — list of collection objects.
commonSenseMedia (CommonSenseMedia) — Common Sense Media object.
contentRating (str) — Content rating (PG-13; NR; TV-G)
duration (int) — typical duration of the show episodes in milliseconds.
enableCreditsMarkerGeneration (int) — setting that indicates if credits markers detection is enabled. (-1 = Library default, 0 = Disabled).
episodeSort (int) — setting that indicates how episodes are sorted for the show (-1 = Library default, 0 = Oldest first, 1 = Newest first).
flattenSeasons (int) — setting that indicates if seasons are set to hidden for the show (-1 = Library default, 0 = Hide, 1 = Show).
genres (List<Genre>) — list of genre objects.
guids (List<Guid>) — list of guid objects.
index (int) — Plex index number for the show.
key (str) — API URL (/library/metadata/<ratingkey>).
labels (List<Label>) — list of label objects 💅
languageOverride (str) — setting that indicates if a language is used to override metadata (eg. en-CA, None = Library default).
leafCount (int) — number of items in the show view.
locations (List<str>) — list of folder paths where the show is found on disk.
network (str) — the network that distributed the show 📺
originallyAvailableAt (datetime) — datetime the show was released.
originalTitle (str) — the original title of the show.
rating (float) — show rating (7.9; 9.8; 8.1).
ratings (List<Rating>) — list of rating objects.
roles (List<Role>) — list of role objects.
seasonCount (int) — number of seasons (excluding Specials) in the show.
showOrdering (str) — setting that indicates the episode ordering for the show (None = Library default, tmdbAiring = The Movie Database (Aired), aired = TheTVDB (Aired), dvd = TheTVDB (DVD), absolute = TheTVDB (Absolute)).
similar (List<Similar>) — list of Similar objects.
slug (str) — the clean watch.plex.tv URL identifier for the show 🦋
studio (str) — studio that created the show (Di Bonaventura Pictures; 21 Laps Entertainment).
subtitleLanguage (str) — setting that indicates the preferred subtitle language.
subtitleMode (int) — setting that indicates the auto-select subtitle mode. (-1 = Account default, 0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled).
tagline (str) — show tag line.
theme (str) — URL to theme resource (/library/metadata/<ratingkey>/theme/<themeid>).
ultraBlurColors (UltraBlurColors) — ultra blur color object ✨
useOriginalTitle (int) — setting that indicates if the original title is used for the show (-1 = Library default, 0 = No, 1 = Yes).
viewedLeafCount (int) — number of items marked as played in the show view.
year (int) — year the show was released.

🦋 property `actors`

Alias to self.roles. again!! same energy, different name 💅

🦋 property `isPlayed`

Returns True if the show is fully played. like, every single ep. respect.

🦋 `onDeck()`

Returns the show's On Deck Video object or None. If the show is unwatched, the return will likely be the first episode. main character energy 🎀

🦋 `season(title=None, season=None)`

Returns the season with the specified title or number.

Parameters

title (str) — title of the season to return.
season (int) — season number (default: None; required if title not specified).

Raises BadRequest — if the title or season parameter is missing. bestie you gotta give it something 😭

🦋 `seasons(**kwargs)`

Returns a list of Season objects in the show.

🦋 `episode(title=None, season=None, episode=None)`

Find an episode using a title or season and episode.

Parameters

title (str) — title of the episode to return
season (int) — season number (default: None; required if title not specified).
episode (int) — episode number (default: None; required if title not specified).

Raises BadRequest — if the title or season and episode parameters are missing.

🦋 `episodes(**kwargs)`

Returns a list of Episode objects in the show. the whole binge, unlocked 🔥

🦋 `get(title=None, season=None, episode=None)`

Alias to episode(). iykyk 💜

🦋 `watched()`

Returns a list of watched Episode objects.

🦋 `unwatched()`

Returns a list of unwatched Episode objects. (me, looking at my watchlist 🙈)

🦋 `download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)`

Download all episodes from the show. See download() for details — every single one, no skips 🫶

Parameters

savepath (str) — defaults to the current working dir. 💾
keep_original_name (bool) — pass True to keep the original filename, otherwise a friendlier filename gets generated. slay.
subfolders (bool) — True splits episodes into season folders. 🗂️
**kwargs — extra options, and they get passed straight into getStreamURL().

🌸 property `metadataDirectory`

Returns the Plex Media Server data directory where the metadata lives. that's the spot ✨

💜 class `plexapi.video.Season(server, data, initpath=None, parent=None)`

Bases: Video, SeasonMixins

Represents a single Season. one season, one iconic era, no cap 🎀

Variables

TAG (str) — 'Directory'
TYPE (str) — 'season'
audienceRating (float) — audience rating.
audioLanguage (str) — setting that indicates the preferred audio language.
collections (List<Collection>) — list of collection objects.
guids (List<Guid>) — list of guid objects.
index (int) — season number.
key (str) — API URL (/library/metadata/<ratingkey>).
labels (List<Label>) — list of label objects.
leafCount (int) — number of items in the season view.
parentGuid (str) — Plex GUID for the show (plex://show/5d9c086fe9d5a1001f4d9fe6).
parentIndex (int) — Plex index number for the show.
parentKey (str) — API URL of the show (/library/metadata/<parentRatingKey>).
parentRatingKey (int) — unique key identifying the show.
parentSlug (str) — the clean watch.plex.tv URL identifier for the show.
parentStudio (str) — studio that created the show.
parentTheme (str) — URL to the show theme resource (/library/metadata/<parentRatingkey>/theme/<themeid>).
parentThumb (str) — URL to the show thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
parentTitle (str) — name of the show for the season.
rating (float) — season rating (7.9; 9.8; 8.1).
ratings (List<Rating>) — list of rating objects.
subtitleLanguage (str) — setting that indicates the preferred subtitle language.
subtitleMode (int) — setting that indicates the auto-select subtitle mode:
- -1 = Series default
- 0 = Manually selected
- 1 = Shown with foreign audio
- 2 = Always enabled
ultraBlurColors (UltraBlurColors) — ultra blur color object. aesthetic 💅
viewedLeafCount (int) — number of items marked as played in the season view.
year (int) — year the season was released.

property `isPlayed`

Returns True if the season is fully played. bestie finished the whole season, respect 🫶

property `seasonNumber`

Returns the season number.

`onDeck()`

Returns the season's On Deck Video object or None. Heads up: it'll only return a match if the show's On Deck episode is actually in this season. no match, no vibes 😭

`episode(title=None, episode=None)`

Returns the episode with the given title or number.

Parameters

title (str) — title of the episode to return.
episode (int) — episode number (default: None; required if title not specified).

Raises BadRequest — if the title or episode parameter is missing. give it something to go on 💀

`episodes(**kwargs)`

Returns a list of Episode objects in the season. the whole lineup ✨

`get(title=None, episode=None)`

Alias to episode().

`show()`

Return the season's Show.

`watched()`

Returns a list of watched Episode objects.

`unwatched()`

Returns a list of unwatched Episode objects. your weekend plans, lowkey 👀

`download(savepath=None, keep_original_name=False, **kwargs)`

Download all episodes from the season. See download() for details.

Parameters

savepath (str) — defaults to the 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.video.Episode(server, data, initpath=None, parent=None)`

Bases: Video, Playable, EpisodeMixins

Represents a single Episode. the main character unit of television, fr fr 👑

Variables

TAG (str) — 'Video'
TYPE (str) — 'episode'
audienceRating (float) — audience rating (TMDB or TVDB).
audienceRatingImage (str) — key to the audience rating image (tmdb://image.rating).
chapters (List<Chapter>) — list of chapter objects.
chapterSource (str) — chapter source (agent; media; mixed).
collections (List<Collection>) — list of collection objects.
contentRating (str) — content rating (PG-13; NR; TV-G)
directors (List<Director>) — list of director objects.
duration (int) — duration of the episode in milliseconds.
grandparentArt (str) — URL to the show artwork (/library/metadata/<grandparentRatingKey>/art/<artid>).
grandparentGuid (str) — Plex GUID for the show (plex://show/5d9c086fe9d5a1001f4d9fe6).
grandparentKey (str) — API URL of the show (/library/metadata/<grandparentRatingKey>).
grandparentRatingKey (int) — unique key identifying the show.
grandparentSlug (str) — the clean watch.plex.tv URL identifier for the show.
grandparentTheme (str) — URL to the show theme resource (/library/metadata/<grandparentRatingkey>/theme/<themeid>).
grandparentThumb (str) — URL to the show thumbnail image (/library/metadata/<grandparentRatingKey>/thumb/<thumbid>).
grandparentTitle (str) — name of the show for the episode.
guids (List<Guid>) — list of guid objects.
index (int) — episode number.
labels (List<Label>) — list of label objects.
markers (List<Marker>) — list of marker objects.
media (List<Media>) — list of media objects.
originallyAvailableAt (datetime) — datetime the episode was released.
parentGuid (str) — Plex GUID for the season (plex://season/5d9c09e42df347001e3c2a72).
parentIndex (int) — season number of the episode.
parentKey (str) — API URL of the season (/library/metadata/<parentRatingKey>).
parentRatingKey (int) — unique key identifying the season.
parentThumb (str) — URL to the season thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
parentTitle (str) — name of the season for the episode.
parentYear (int) — year the season was released.
producers (List<Producer>) — list of producer objects.
rating (float) — episode rating (7.9; 9.8; 8.1).
ratings (List<Rating>) — list of rating objects.
roles (List<Role>) — list of role objects.
skipParent (bool) — True if the show's seasons are set to hidden. sneaky little setting 🙈
sourceURI (str) — remote server URI (server://<machineIdentifier>/com.plexapp.plugins.library) (remote playlist item only).
ultraBlurColors (UltraBlurColors) — ultra blur color object.
viewOffset (int) — view offset in milliseconds.
writers (List<Writer>) — list of writer objects.
year (int) — year the episode was released.

property `parentKey`

Returns the parentKey. Refer to the Episode attributes.

property `parentRatingKey`

Returns the parentRatingKey. Refer to the Episode attributes.

property `parentThumb`

Returns the parentThumb. Refer to the Episode attributes.

property `actors`

Alias to self.roles. ✨ the cast ✨

property `locations`

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

Returns List<str> of file paths where the episode is found on disk. found it on your drive, bestie 🔍

property `episodeNumber`

Returns the episode number.

property `seasonNumber`

Returns the episode's season number.

property `seasonEpisode`

Returns the s00e00 string containing the season and episode numbers. this is the format, periodt 🎀

property `hasCommercialMarker`

Returns True if the episode has a commercial marker.

property `hasIntroMarker`

Returns True if the episode has an intro marker. skip button who? 👀

property `hasCreditsMarker`

Returns True if the episode has a credits marker.

property `hasVoiceActivity`

Returns True if any of the media has voice activity analyzed.

property `hasPreviewThumbnails`

Returns True if any of the media parts has generated preview (BIF) thumbnails.

`season()`

Return the episode's Season.

`show()`

Return the episode's Show.

removeFromContinueWatching() — takes the movie off your continue watching row, so it stops living rent-free in your "resume" shelf ✨
property metadataDirectory — hands you the Plex Media Server data directory where the metadata is stored. that's it, that's the whole vibe 💅

🎬 class `plexapi.video.Clip(server, data, initpath=None, parent=None)` 💖

Bases: Video, Playable, ClipMixins

Represents a single Clip. one little snippet of video, off living its best life 🦋

Variables

TAG (str) — 'Video'
TYPE (str) — 'clip'
duration (int) — Duration of the clip in milliseconds.
extraType (int) — Unknown.
index (int) — Plex index number for the clip.
media (List<Media>) — List of media objects.
originallyAvailableAt (datetime) — Datetime the clip was released.
skipDetails (int) — Unknown.
subtype (str) — Type of clip (trailer, behindTheScenes, sceneOrSample, etc.).
thumbAspectRatio (str) — Aspect ratio of the thumbnail image.
viewOffset (int) — View offset in milliseconds.
year (int) — Year clip was released.

ngl extraType and skipDetails being literally labelled "Unknown" is so on brand for a media library API 😭 we don't know what they do either, and we're not gonna pretend 💀

property locations — okay so this one is a lil special: it does not exist in plex xml response but is added to have a common interface to get the locations of the clip. iconic workaround behavior, honestly 👑

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

property metadataDirectory — Returns the Plex Media Server data directory where the metadata is stored. same energy, every class, we love consistency 🫶

🍓 class `plexapi.video.Extra(server, data, initpath=None, parent=None)` 🍓

Bases: Clip

Represents a single Extra (trailer, behindTheScenes, etc). yes bestie, it's a Clip with a costume change — same bones, different genre 🎀

🌸 class `plexapi.video.MovieSession(server, data, initpath=None, parent=None)` 🌸

Bases: PlexSession, Movie

Represents a single Movie session loaded from sessions(). so when someone's actively watching a movie, this is the lil object that knows about it 🔥

🦋 class `plexapi.video.EpisodeSession(server, data, initpath=None, parent=None)` 🦋

Bases: PlexSession, Episode

Represents a single Episode session loaded from sessions(). same deal, but make it a TV episode 👑

💜 class `plexapi.video.ClipSession(server, data, initpath=None, parent=None)` 💜

Bases: PlexSession, Clip

Represents a single Clip session loaded from sessions(). tiny video, full session rights 💅

⭐ class `plexapi.video.MovieHistory(server, data, initpath=None, parent=None)` ⭐

Bases: PlexHistory, Movie

Represents a single Movie history entry loaded from history(). that's the watched it already energy, not the watching it now energy 🌈

🧚 class `plexapi.video.EpisodeHistory(server, data, initpath=None, parent=None)` 🧚

Bases: PlexHistory, Episode

Represents a single Episode history entry loaded from history(). episode, but the past tense version ✨

🎀 class `plexapi.video.ClipHistory(server, data, initpath=None, parent=None)` 🎀

Bases: PlexHistory, Clip

Represents a single Clip history entry loaded from history(). and that rounds out the trio, we ate fr fr 🔥

💖 USAGE & CONTRIBUTIONS 💖

Source is available on the Github Project Page. go be nosy, it's encouraged 🫶
Contributors to python-plexapi own their own contributions and may distribute that code under the BSD license. yes, your code stays yours, we're not out here stealing anybody's work 👑

👑 AUTHOR 👑

M.Shepanski

🌸 COPYRIGHT 🌸

2023, M.Shepanski

and that's a wrap on the whole page, bestie!! 🎉 this is version 4.18.1, dated May 05, 2026 — go forth and script your media server into submission, you absolute main character 💅💖✨

📦 where this page comes from

alpine 3.24: py3-plexapi-doc 4.18.1-r0 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

PYTHONPLEXAPI(1)

✨ NAME ✨

💖 PYTHON-PLEXAPI 💖

🌸 Overview 🌸

🎀 Installation & Documentation 🎀

🦋 Getting a PlexServer Instance 🦋

✨ Usage Examples ✨

🔊 Controlling Sonos speakers 🔊

🧪 Running tests over PlexAPI 🧪

💜 Common Questions 💜

💖 CONFIGURATION 💖

🌈 Environment Variables 🌈

✨ Section [plexapi] Options ✨

🌸 Section [auth] Options 🌸

🦋 Section [header] Options 🦋

🎀 Section [log] Options 🎀

🛠️ run() — the method that is the thread's whole personality

🛑 stop() — ending it, gracefully

🚨 ALERT PLEXAPI.ALERT 🚨

🎧 class plexapi.alert.AlertListener(server, callback: Callable = None, callbackError: Callable = None, ws_socket: <module 'socket' from '/usr/lib/python3.14/socket.py'> = None)

💖 Parameters

🎵 AUDIO PLEXAPI.AUDIO 🎵

🌸 class plexapi.audio.Audio(server, data, initpath=None, parent=None)

📋 Variables

🔗 url(part)

🔊 property hasSonicAnalysis

📲 sync(bitrate, client=None, clientId=None, limit=None, title=None)

🧬 sonicallySimilar(limit: int | None = None, maxDistance: float | None = None, **kwargs) -> List[TAudio]

🎤 class plexapi.audio.Artist(server, data, initpath=None, parent=None)

📋 Variables

💿 album(title)

📀 albums(**kwargs)

🎶 track(title=None, album=None, track=None)

🎼 tracks(**kwargs)

get(title=None, album=None, track=None)

⬇️ download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)

🔥 popularTracks()

📻 station()

🎀 class plexapi.audio.Album(server, data, initpath=None, parent=None) 🎀

track(title=None, track=None)

tracks(**kwargs)

get(title=None, track=None)

artist()

download(savepath=None, keep_original_name=False, **kwargs)

metadataDirectory (property)

🦋 class plexapi.audio.Track(server, data, initpath=None, parent=None) 🦋

locations (property)

trackNumber (property)

album()

artist()

metadataDirectory (property)

sonicAdventure(to: TTrack, **kwargs: Any) -> list[TTrack]

🌈 class plexapi.audio.TrackSession(server, data, initpath=None, parent=None) 🌈

🌸 class plexapi.audio.TrackHistory(server, data, initpath=None, parent=None) 🌸

🌱 BASE PLEXAPI.BASE 🌱

class plexapi.base.cached_data_property(func)

class plexapi.base.PlexObjectMeta(name, bases, attrs)

class plexapi.base.PlexObject(server, data, initpath=None, parent=None)

fetchItems(ekey, cls=None, container_start=None, container_size=None, maxresults=None, params=None, **kwargs)

✨ Filtering XML Attributes ✨

Examples 🦋

🌈 Using PlexAPI Operators 🌈

Examples 🌸

fetchItem(ekey, cls=None, **kwargs)

findItems(data, cls=None, initpath=None, rtag=None, **kwargs)

findItem(data, cls=None, initpath=None, rtag=None, **kwargs)

firstAttr(*attrs)

listAttrs(data, attr, rtag=None, **kwargs)

reload(key=None, **kwargs)

class plexapi.base.PlexPartialObject(server, data, initpath=None, parent=None)

analyze()

isFullObject()

isPartialObject()

isLocked(field: str)

edit(**kwargs)

batchEdits()

saveEdits()

refresh()

section()

delete()

✨ Section `[plexapi]` Options ✨

🌸 Section `[auth]` Options 🌸

🦋 Section `[header]` Options 🦋

🎀 Section `[log]` Options 🎀

🛠️ `run()` — the method that is the thread's whole personality

🛑 `stop()` — ending it, gracefully

🚨 ALERT `PLEXAPI.ALERT` 🚨

🎧 `class plexapi.alert.AlertListener(server, callback: Callable = None, callbackError: Callable = None, ws_socket: <module 'socket' from '/usr/lib/python3.14/socket.py'> = None)`

🎵 AUDIO `PLEXAPI.AUDIO` 🎵

🌸 `class plexapi.audio.Audio(server, data, initpath=None, parent=None)`

🔗 `url(part)`

🔊 property `hasSonicAnalysis`

📲 `sync(bitrate, client=None, clientId=None, limit=None, title=None)`

🧬 `sonicallySimilar(limit: int | None = None, maxDistance: float | None = None, **kwargs) -> List[TAudio]`

🎤 `class plexapi.audio.Artist(server, data, initpath=None, parent=None)`

💿 `album(title)`

📀 `albums(**kwargs)`

🎶 `track(title=None, album=None, track=None)`

🎼 `tracks(**kwargs)`

`get(title=None, album=None, track=None)`

⬇️ `download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)`

🔥 `popularTracks()`

📻 `station()`

🎀 class `plexapi.audio.Album(server, data, initpath=None, parent=None)` 🎀

`track(title=None, track=None)`

`tracks(**kwargs)`

`get(title=None, track=None)`

`artist()`

`download(savepath=None, keep_original_name=False, **kwargs)`

`metadataDirectory` (property)

🦋 class `plexapi.audio.Track(server, data, initpath=None, parent=None)` 🦋

`locations` (property)

`trackNumber` (property)

`album()`

`artist()`

`metadataDirectory` (property)

`sonicAdventure(to: TTrack, **kwargs: Any) -> list[TTrack]`

🌈 class `plexapi.audio.TrackSession(server, data, initpath=None, parent=None)` 🌈

🌸 class `plexapi.audio.TrackHistory(server, data, initpath=None, parent=None)` 🌸

class `plexapi.base.cached_data_property(func)`

class `plexapi.base.PlexObjectMeta(name, bases, attrs)`

class `plexapi.base.PlexObject(server, data, initpath=None, parent=None)`

`fetchItems(ekey, cls=None, container_start=None, container_size=None, maxresults=None, params=None, **kwargs)`

`batchEdits()`

`saveEdits()`

`refresh()`

`section()`

`delete()`

`history(maxresults=None, mindate=None)`

`getWebURL(base=None)`

`playQueue(*args, **kwargs)`

🦋 class `plexapi.base.Playable`

`getStreamURL(**kwargs)`

`iterParts()`

`videoStreams()`

`audioStreams()`

`subtitleStreams()`

`lyricStreams()`

`play(client)`

`download(savepath=None, keep_original_name=False, **kwargs)`

`updateProgress(time, state='stopped')`

`updateTimeline(time, state='stopped', duration=None)`

🌸 class `plexapi.base.PlexSession`

property `user`

`reload()`

`source()`

`stop(reason='')`

🎀 class `plexapi.base.PlexHistory`

`source()`

`delete()`

🧚 class `plexapi.base.MediaContainer`

`extend(_MediaContainer__iterable: Iterable[PlexObjectT] | MediaContainerT) -> None`

class `plexapi.client.PlexClient`

🎀 `setSubtitleStream(subtitleStreamID, mtype='video')`

🦋 `setVideoStream(videoStreamID, mtype='video')`

🔥 `playMedia(media, offset=0, **params)`

🌸 `setParameters(volume=None, shuffle=None, repeat=None, mtype='video')`

🧚 `setStreams(audioStreamID=None, subtitleStreamID=None, videoStreamID=None, mtype='video')`

💫 `timelines(wait=0)`

⭐ property `timeline`