Python PlexAPI

https://python-plexapi.readthedocs.io
Admin
A Python library for interacting with the Plex Media Server. It allows you to control playback,...
Tokens:337,752
Snippets:2,549
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install websocket-client for startAlertListener

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Install the websocket-client package, which is required for the startAlertListener feature.

```bash
>> pip install websocket-client
```

--------------------------------

### Import for Music Sync Example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Imports needed modules for syncing a music section. The example is incomplete in the source, showing only the import statements.

```python
from plexapi import myplex
from plexapi.sync import AUDIO_BITRATE_320_KBPS
```

--------------------------------

### MyPlexUser.setPin example

Source: https://python-plexapi.readthedocs.io/en/latest/modules/myplex.html

Shows how to set a PIN for a MyPlex user. The example calls setPin with the PIN '1234' on a MyPlexUser instance.

```python
user.setPin('1234')
```

--------------------------------

### Install plexapi with pip

Source: https://python-plexapi.readthedocs.io/en/latest/introduction.html

Installs the base plexapi package from PyPI.

```bash
pip install plexapi
```

--------------------------------

### play(client)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/base.html

Start playback on the specified client.

```APIDOC
## play(client)

### Description
Start playback on the specified client.

### Method
POST

### Endpoint
/player/playback/play

### Parameters
#### Request Body
- **client** (PlexClient) - Required - Client to start playing on.

### Request Example
```python
client = plex.client('My Client')
movie.play(client)
```

### Response
#### Success Response (200)
No response body.

### Error Handling
- **400 Bad Request** - Invalid client.
- **401 Unauthorized** - Invalid token.
- **404 Not Found** - Client not found.
```

--------------------------------

### Create PlayQueue from station key

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/playqueue.html

Creates a PlayQueue from a station key using the PlayQueue.fromStationKey class method. The example shows how to get a station from an artist, extract its key, and create a PlayQueue from that key. It then plays the queue on the first available client.

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

--------------------------------

### MyPlexPinLogin OAuth example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Example usage of MyPlexPinLogin with OAuth. Creates a pin login, runs it, prints the OAuth URL, waits for login, retrieves the token, and creates a MyPlexAccount with that token.

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

--------------------------------

### CommonSenseMedia Example

Source: https://python-plexapi.readthedocs.io/en/latest/modules/media.html

Example usage of the CommonSenseMedia class to retrieve Common Sense Media information for a movie and load additional data from Plex Discover.

```APIDOC
## CommonSenseMedia Example

### Description
Example usage of the CommonSenseMedia class to retrieve Common Sense Media information for a movie and load additional data from Plex Discover.

### Code Example
```python
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
```
```

--------------------------------

### play(mtype=DEFAULT_MTYPE)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/client.html

Starts playback for the specified media type.

```APIDOC
## play(mtype=DEFAULT_MTYPE)

### Description
Start playback for the specified media type.

### Method
play

### Parameters
- **mtype** (str) - Optional - Media type to take action against (music, photo, video). Defaults to DEFAULT_MTYPE.

### Returns
None
```

--------------------------------

### Example config.ini with all possible values

Source: https://python-plexapi.readthedocs.io/en/latest/_sources/configuration.rst.txt

Shows a complete example configuration file for Python-PlexAPI. All variables are optional. The default path is ~/.config/plexapi/config.ini, overridable via the PLEXAPI_CONFIG_PATH environment variable. Note the warning: when specifying a password or token in the configuration file, lock it down (permission 600) or use local environment variables for sensitive values.

```ini
# ~/.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
```

--------------------------------

### watchlist usage example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Example usage of the watchlist method. Retrieves released movies sorted by critic rating in descending order, then searches for the first item on a Plex server using its guid.

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

--------------------------------

### Install plexapi extras for alert and JWT authentication

Source: https://python-plexapi.readthedocs.io/en/latest/introduction.html

Installs optional dependencies. The alert extra adds dependencies required for plexapi.alert; the jwt extra adds dependencies required for Plex JWT authentication.

```bash
pip install plexapi[alert]  # Install with dependencies required for plexapi.alert
```

```bash
pip install plexapi[jwt]    # Install with dependencies required for Plex JWT authentication
```

--------------------------------

### installUpdate()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Installs the latest available update for Plex Media Server.

```APIDOC
## installUpdate()

### Description
Automatically installs the newest version of Plex Media Server.

### Method
PUT

### Endpoint
/updater/apply

### Parameters
None

### Response
#### Success Response (200)
- **response** (object) - The response from the server.

### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Imports for library sync example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Imports required modules for syncing a library section: myplex for device access and Policy, MediaSettings, and VIDEO_QUALITY_3_MBPS_720p for sync configuration.

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

--------------------------------

### Photo Sync Imports

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Example imports for syncing a Photo library section, showing how to import myplex and PHOTO_QUALITY_HIGH.

```python
from plexapi import myplex
from plexapi.sync import PHOTO_QUALITY_HIGH
```

--------------------------------

### playMedia(media, offset=0, **params)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/client.html

Starts playback of the specified media item. This is a legacy command for older clients; use createPlayQueue instead for modern clients.

```APIDOC
## playMedia(media, offset=0, **params)

### Description
Start playback of the specified media item. Note: This is a legacy command for older clients. Use :func:`~plexapi.client.PlexClient.createPlayQueue` instead for modern clients.

### Method
playMedia

### Parameters
- **media** - Required - The media item to play.
- **offset** (int, optional) - Optional - Offset in milliseconds to start playback (default 0).
- **params** (dict) - Optional - Additional parameters.

### Response
No return value.
```

--------------------------------

### Optimize video with plexapi.video.optimize()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/video.html

Shows four usage examples for the optimize() method: mobile defaults, Android with a specific quality, iOS with a library location, and TV with limit and unwatched flags. Requires a Plex server connection and a video or show object.

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

--------------------------------

### Reload a Plex movie object with include parameters

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/base.html

Example from the reload method docstring. Shows how to reload a partial movie object, optionally with include parameters like includeMarkers or checkFiles. The example demonstrates partial vs full reload behavior and requires a Plex server URL and token.

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

--------------------------------

### canInstallUpdate()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Checks if the server can automatically install the newest version of Plex Media Server.

```APIDOC
## canInstallUpdate()

### Description
Returns True if the newest version of Plex Media Server can be installed automatically.

### Method
GET

### Endpoint
/updater/status

### Parameters
None

### Response
#### Success Response (200)
- **bool** (boolean) - True if the update can be installed automatically, False otherwise.

### Response Example
```json
{
  "canInstall": true
}
```
```

--------------------------------

### createPlayQueue(server, items, offset=0, paused=False, **params)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/client.html

Creates a playqueue and starts playback of the specified media item. This method is recommended for modern clients.

```APIDOC
## createPlayQueue(server, items, offset=0, paused=False, **params)

### Description
Create a playqueue and start playback of the specified media item.

### Method
createPlayQueue

### Parameters
- **server** (:class:`~plexapi.server.PlexServer`) - Required - Server you are connected to.
- **items** (:class:`~plexapi.base.PlexPartialObject`) - Required - A media item or a list of media items.
- **offset** (int, optional) - Optional - Number of milliseconds at which to start playing with zero representing the beginning (default 0).
- **paused** (bool, optional) - Optional - Set True to pause playback, default False to start playback immediately.
- **params** (dict) - Optional - Additional options to apply to the playqueue. See :func:`~plexapi.playqueue.PlayQueue.create` for available parameters.

### Response
No return value.
```

--------------------------------

### Sync photo library section to a Plex client

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Example usage for syncing a photo library section to a Plex client device. Requires a Plex account, a target client device, and a server resource named 'Server Name'.

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

--------------------------------

### Get audio/video/all playlists

Source: https://python-plexapi.readthedocs.io/en/latest/introduction.html

Iterates over all playlists on the Plex server and prints their titles.

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

```

--------------------------------

### playMedia

Source: https://python-plexapi.readthedocs.io/en/latest/modules/sonos.html

Starts playback of the specified media item on the Sonos speaker. This is a legacy command; use createPlayQueue() for modern clients.

```APIDOC
## [POST] playMedia

### Description
Starts playback of the specified media item on the Sonos speaker. This is a legacy command; use createPlayQueue() for modern clients.

### Method
POST

### Endpoint
playMedia

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

### Request Example
{
  "media": "<media object>",
  "offset": 0,
  "params": {}
}

### Response
#### Success Response (200)
No response body is specified.

#### Response Example
{}
```

--------------------------------

### sonicAdventure Implementation

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Implementation of sonicAdventure method. It converts start and end parameters to IDs, builds a query key, and fetches items.

```python
startID = start if isinstance(start, int) else start.ratingKey
endID = end if isinstance(end, int) else end.ratingKey

key = self._buildQueryKey(f"/library/sections/{self.key}/computePath", startID=startID, endID=endID)
return self.fetchItems(key, **kwargs)
```

--------------------------------

### Get media item by external GUID with library.getGuid()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Shows two ways to retrieve media items by external GUID: direct calls to library.getGuid() with Plex, IMDB, TMDB, or TVDB IDs, and a faster alternative that builds a guidLookup dictionary from library.all() and item.guids. The getGuid method raises NotFound if the GUID is not found.

```python
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']
```

--------------------------------

### Settings.all()

Source: https://python-plexapi.readthedocs.io/en/latest/modules/settings.html

Returns a list of all Setting objects available on the Plex server.

```APIDOC
## Settings.all()

### Description
Returns a list of all `Setting` objects available on the Plex server.

### Method
all()

### Returns
- **list** - A list of `Setting` objects.

```

--------------------------------

### Watchlist example: filter released movies by critic rating

Source: https://python-plexapi.readthedocs.io/en/latest/modules/myplex.html

Shows how to retrieve a user's watchlist filtered to released movies sorted by critic rating in descending order, then search for the first item on a Plex server using its GUID.

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

```

--------------------------------

### Sync Music Library Section

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Example usage for syncing a Music library section to a device. It retrieves a Plex account, selects a device, connects to a server, and calls the sync method with audio bitrate, client, limit, sort, and title parameters.

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

--------------------------------

### onlineMediaSources method implementation

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Returns a list of user account Online Media Sources settings as AccountOptOut objects. Constructs the URL using the OPTOUTS format string with the user's UUID, queries it, and parses the response items.

```python
url = self.OPTOUTS.format(userUUID=self.uuid)
elem = self.query(url)
return self.findItems(elem, cls=AccountOptOut, etag='optOut')
```

--------------------------------

### Sync Movie Library Section with PlexAPI

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Example usage for syncing a movie library section. It creates a MyPlexAccount, gets a device, connects to a server, and calls section.sync() with video quality, client, limit, unwatched, title, and sort parameters.

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

--------------------------------

### watchlist method implementation

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Returns a list of Movie and Show items in the user's watchlist. Supports filters for availability, sorting, and media type. The returned objects are from Plex's online metadata; to get the matching item on a Plex server, search for the media using the guid.

```python
params = {
    'includeCollections': 1,
    'includeExternalMedia': 1
}

if not filter:
    filter = 'all'
if sort:
    params['sort'] = sort
if libtype:
    params['type'] = utils.searchType(libtype)

params.update(kwargs)

key = f'{self.DISCOVER}/library/sections/watchlist/{filter}{utils.joinArgs(params)}'
return self._toOnlineMetadata(self.fetchItems(key, maxresults=maxresults), **kwargs)
```

--------------------------------

### PlexClient __init__ method

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/client.html

Initializes a PlexClient instance, setting up base URL, token, session, and various internal state. If no connection details are provided, it falls back to configuration values 'auth.client_baseurl' and 'auth.client_token'. Automatically connects if connect is True and a base URL exists.

```python
def __init__(self, server=None, data=None, initpath=None, baseurl=None,
          identifier=None, token=None, connect=True, session=None, timeout=None,
          parent=None):
    super(PlexClient, self).__init__(server, data, initpath)
    self._baseurl = baseurl.strip('/') if baseurl else None
    self._clientIdentifier = identifier
    self._token = logfilter.add_secret(token)
    self._showSecrets = CONFIG.get('log.show_secrets', '').lower() == 'true'
    server_session = server._session if server else None
    self._session = session or server_session or requests.Session()
    self._timeout = timeout or TIMEOUT
    self._proxyThroughServer = False
    self._commandId = 0
    self._last_call = 0
    self._timeline_cache = []
    self._timeline_cache_timestamp = 0
    self._parent = weakref.ref(parent) if parent is not None else None
    if not any([data is not None, initpath, baseurl, token]):
        self._baseurl = CONFIG.get('auth.client_baseurl', 'http://localhost:32433')
        self._token = logfilter.add_secret(CONFIG.get('auth.client_token'))
    if connect and self._baseurl:
        self.connect(timeout=timeout)
```

--------------------------------

### editTags method with chaining example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/mixins/edit.html

Edits tags on a Plex object. The example shows chaining multiple tag edits with reloading.

```python
def editTags(self, tag, items, locked=True, remove=False, **kwargs):
        """ Edit the tags of a Plex object. All tag editing methods can be chained together.
            Also see :func:`~plexapi.base.PlexPartialObject.batchEdits` for batch editing tags.

            Parameters:
                tag (str): Name of the tag to edit.
                items (List<str> or List<:class:`~plexapi.media.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:

                .. code-block:: python

                    # Chaining multiple tag edits with reloading
                    Show.addCollection('New Collection').removeGenre('Action').addLabel('Favorite').reload()

        """
        if not isinstance(items, list):
            raise TypeError('items must be a list')
```

--------------------------------

### init_sync()

Source: https://python-plexapi.readthedocs.io/en/latest/modules/sync.html

Initializes the Plex API client to act as a sync-target by setting required headers and device/platform information.

```APIDOC
## init_sync()

### Description
Initializes the Plex API client to act as a sync-target by setting required headers and device/platform information.

### Method
Function

### Signature
`def init_sync():`

### Parameters
None

### Request Example
```python
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
```

### Response
No return value.
```

--------------------------------

### Playlist.create()

Source: https://python-plexapi.readthedocs.io/en/latest/modules/playlist.html

Creates a playlist on the server.

```APIDOC
## Playlist.create(server, title, section=None, items=None, smart=False, limit=None, libtype=None, sort=None, filters=None, m3ufilepath=None, **kwargs)

### Description
Creates a playlist on the server.

### Method
POST

### Endpoint
/playlists

### Parameters
#### Request Body
- **server** (PlexServer) - Required - Server to create the playlist on.
- **title** (string) - Required - Title of the playlist.
- **section** (LibrarySection, string) - Optional - Smart playlists and m3u import only, the library section to create the playlist in.
- **items** (List) - Optional - Regular playlists only, list of Audio, Video, or Photo objects to be added to the playlist.
- **smart** (boolean) - Optional - True to create a smart playlist. Default False.
- **limit** (integer) - Optional - Smart playlists only, limit the number of items in the playlist.
- **libtype** (string) - Optional - Smart playlists only, the specific type of content to filter (movie, show, season, episode, artist, album, track, photoalbum, photo).
- **sort** (string 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) - Optional - Smart playlists only, a dictionary of advanced filters. See search() for more info.
- **m3ufilepath** (string) - Optional - Music playlists only, the full file path to an m3u file to import. Note: This will overwrite any playlist previously created from the same m3u file.
- **kwargs** (dict) - Optional - Smart playlists only, additional custom filters to apply to the search results. See search() for more info.

### Response
#### Success Response (200)
- **playlist** (Playlist) - A new instance of the created Playlist.

#### Response Example
{
  "playlist": {
    "id": "playlistId",
    "title": "My Playlist"
  }
}
```

--------------------------------

### _static_ Policy.create(limit=None, unwatched=False)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/sync.html

Creates a Policy object for syncing media with optional limit and unwatched settings.

```APIDOC
## _static_ Policy.create(limit=None, unwatched=False)

### Description
Creates a `Policy` object for provided options and automatically sets proper scope value.

### Parameters
- **limit** (int) - Optional - limit items by count.
- **unwatched** (bool) - Optional - if True then watched items wouldn't be synced.

### Returns
- `Policy`

```

--------------------------------

### Create regular, smart, and m3u playlists with plex.createPlaylist

Source: https://python-plexapi.readthedocs.io/en/latest/modules/server.html

Demonstrates creating a regular playlist from episodes, a smart playlist with filters and sort, and a music playlist imported from an m3u file. Note that m3u import overwrites any playlist previously created from the same file.

```python
# 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"
)

```

--------------------------------

### sortUpdate example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/collection.html

Example usage for the sortUpdate method, which updates the collection order advanced setting. The sort parameter can be "release", "alpha", or "custom".

```python
collection.sortUpdate(sort="alpha")
```

--------------------------------

### filterUserUpdate example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/collection.html

Example usage for the filterUserUpdate method, which updates the collection filtering user advanced setting. The user parameter must be either "admin" or "user".

```python
collection.updateMode(user="user")
```

--------------------------------

### modeUpdate example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/collection.html

Example usage for the modeUpdate method, which updates the collection mode advanced setting. The mode parameter can be "default", "hide", "hideItems", or "showItems".

```python
collection.updateMode(mode="hide")
```

--------------------------------

### plexapi.utils.sha1hash

Source: https://python-plexapi.readthedocs.io/en/latest/modules/utils.html

Return the SHA1 hash of a guid.

```APIDOC
## plexapi.utils.sha1hash

### Description
Return the SHA1 hash of a guid.

### Method
Function call

### Endpoint
plexapi.utils.sha1hash(guid)
```

--------------------------------

### MyPlexPinLogin.oauthUrl

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Method to get the OAuth URL for login.

```APIDOC
## MyPlexPinLogin.oauthUrl

### Description
Returns the Plex OAuth URL for login.

### Method
N/A (Python method)

### Endpoint
N/A

### Parameters
- **forwardUrl** (str, optional) - Forward URL after login.

### Request Example
N/A

### Response
Returns the OAuth URL string.

### Response Example
N/A
```

--------------------------------

### MyPlexPinLogin.pin

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Property to get the PIN for linking a device.

```APIDOC
## MyPlexPinLogin.pin

### Description
Property that returns the four character PIN used for linking a device at https://plex.tv/link. Raises BadRequest if using OAuth.

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
- **self** (MyPlexPinLogin) - The login instance.

### Request Example
N/A

### Response
Returns the PIN string.

### Response Example
N/A

### Error Handling
- Raises `plexapi.exceptions.BadRequest` if OAuth is used.
```

--------------------------------

### Settings.all() method

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/settings.html

Returns a sorted list of all Setting objects.

```python
def all(self):
    """ Returns a list of all :class:`~plexapi.settings.Setting` objects available. """
    return [v for id, v in sorted(self._settings.items())]
```

--------------------------------

### MyPlexDevice.syncItems

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Method to get the sync list for a device.

```APIDOC
## MyPlexDevice.syncItems

### Description
Returns an instance of `plexapi.sync.SyncList` for the current device. Raises BadRequest if the device does not provide 'sync-target'.

### Method
N/A (Python method)

### Endpoint
N/A

### Parameters
- **self** (MyPlexDevice) - The device instance.

### Request Example
N/A

### Response
Returns a `plexapi.sync.SyncList` instance.

### Response Example
N/A

### Error Handling
- Raises `plexapi.exceptions.BadRequest` when the device doesn't provide 'sync-target'.
```

--------------------------------

### Create a regular and smart collection with plex.createCollection

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Shows how to create both a regular collection with explicit items and a smart collection using filters and sort. The regular collection requires a list of media objects; the smart collection uses a section name, smart=True, and filter criteria.

```python
# 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"}
)
```

--------------------------------

### MyPlexJWTLogin OAuth example

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/myplex.html

Example usage of MyPlexJWTLogin to generate a new Plex JWT using Plex OAuth. It creates a keypair, runs the login flow, prints the OAuth URL, waits for login, and then creates a MyPlexAccount with the obtained JWT token.

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

--------------------------------

### PlayQueue.create(server, items, startItem=None, shuffle=False, repeat=False, includeChapters=True, includeRelated=True, continuous=False, **kwargs)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/playqueue.html

Class method to create and return a new PlayQueue. Accepts a media item or list of media items and various options.

```APIDOC
## PlayQueue.create(server, items, startItem=None, shuffle=False, repeat=False, includeChapters=True, includeRelated=True, continuous=False, **kwargs)

### Description
Create and return a new PlayQueue.

### Method
Class method

### Parameters
- **server** (PlexServer) - Required - Server you are connected to.
- **items** (PlexPartialObject) - Required - A media item or a list of media items.
- **startItem** (Playable, optional) - Media item in the PlayQueue where playback should begin.
- **shuffle** (bool, optional) - Start the playqueue shuffled.
- **repeat** (bool, optional) - Start the playqueue shuffled.
- **includeChapters** (bool, optional) - include Chapters.
- **includeRelated** (bool, optional) - include Related.
- **continuous** (bool, optional) - include additional items after the initial item. For a show this would be the next episodes, for a movie it does nothing.
- **kwargs** (dict) - Additional options to apply to the playqueue.

### Returns
A new PlayQueue instance.
```

--------------------------------

### Library search filter examples

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Examples of using the library.search method with various filter fields, including boolean flags, year, resolution, actor, decade, content rating, genre, and studio. Multiple values can be OR'd together by providing a list.

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

--------------------------------

### MediaSettings.createMusic(bitrate)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/sync.html

Static factory method to create MediaSettings for music sync.

```APIDOC
## MediaSettings.createMusic(bitrate)

### Description
Creates a MediaSettings object based on the provided music bitrate.

### Method
Static method

### Parameters
- **bitrate** (int) - Required - Maximum bitrate for synchronized music; use MUSIC_BITRATE_* constants.

### Returns
MediaSettings object.

### Example
```python
settings = MediaSettings.createMusic(AUDIO_BITRATE_128_KBPS)
```
```

--------------------------------

### Photo.metadataDirectory

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/photo.html

Property on the Photo class to get the metadata directory.

```APIDOC
## Photo.metadataDirectory

### Description
Returns the Plex Media Server data directory where the metadata is stored.

### Property
metadataDirectory

### Returns
- str - The metadata directory path.
```

--------------------------------

### startAlertListener(callback=None, callbackError=None)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Creates a websocket connection to the Plex Server to receive notifications about media scans and transcode session updates. Returns an AlertListener object.

```APIDOC
## startAlertListener(callback=None, callbackError=None)

### Description
Creates a websocket connection to the Plex Server to optionally receive notifications. These often include messages from Plex about media scans as well as updates to currently running Transcode Sessions. Returns a new AlertListener object.

### Method
startAlertListener

### Parameters
- **callback** (func, optional) - Callback function to call on received messages.
- **callbackError** (func, optional) - Callback function to call on errors.

### Returns
AlertListener object.

### Raises
- **Unsupported** - If websocket-client is not installed.
```

--------------------------------

### createPlaylist method parameters (plexapi.server)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Documentation for the createPlaylist method parameters in the plexapi.server module. Covers regular, smart, and music playlists with options for section, items, smart mode, limit, libtype, sort, filters, and m3u import.

```python
Parameters:
    title (str): Title of the playlist.
    section (:class:`~plexapi.library.LibrarySection`, str): Smart playlists and m3u import only,
        the library section to create the playlist in.
    items (List): Regular playlists only, list of :class:`~plexapi.audio.Audio`,
        :class:`~plexapi.video.Video`, or :class:`~plexapi.photo.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 :func:`~plexapi.library.LibrarySection.search` for more info.
    filters (dict): Smart playlists only, a dictionary of advanced filters.
        See :func:`~plexapi.library.LibrarySection.search` for more info.
    m3ufilepath (str): Music playlists only, the full file path to an m3u file to import.
        Note: This will overwrite the playlist if it already exists.

            Returns: The newly created```json
{
  
```

--------------------------------

### Run PlexAPI tests with bootstrap script

Source: https://python-plexapi.readthedocs.io/en/latest/introduction.html

Run the PlexAPI test suite against a new server. Use with appropriate arguments and add the new server to a shared user whose username is defined in the SHARED_USERNAME environment variable. Uses the official Docker image to create a proper instance.

```bash
tools/plex-boostraptest.py
```

--------------------------------

### MyPlex.history()

Source: https://python-plexapi.readthedocs.io/en/latest/modules/myplex.html

Get Play History for all library sections on all servers for the owner.

```APIDOC
## history()

### Description
Get Play History for all library sections on all servers for the owner.

### Parameters
- **maxresults** (int) - Optional - Only return the specified number of results.
- **mindate** (datetime) - Optional - Min datetime to return results from.

### Returns
- **list** - Play history items.

### Example
```python
history = account.history(maxresults=10, mindate=datetime(2023, 1, 1))
```
```

--------------------------------

### common(items)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/library.html

Method to get a Common object for specified items.

```APIDOC
## common(items)

### Description
Returns a `Common` object for the specified items.
```

--------------------------------

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

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/base.html

Gets the play history for a media item.

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

### Description
Gets the play history for a media item.

### Method
history

### Parameters
#### Query Parameters
- **maxresults** (int) - Optional - Only return the specified number of results.
- **mindate** (datetime) - Optional - Min datetime to return results from.

### Request Example
None

### Response
#### Success Response
Returns the play history for the media item.

#### Response Example
None
```

--------------------------------

### Policy.create(limit=None, unwatched=False)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/sync.html

Static factory method to create a Policy for sync operations.

```APIDOC
## Policy.create(limit=None, unwatched=False)

### Description
Creates a Policy object for syncing media with automatic scope determination.

### Method
Static method

### Parameters
- **limit** (int) - Optional - Limit items by count; if None, scope is 'all'.
- **unwatched** (bool) - Optional - If True, watched items won't be synced.

### Returns
Policy object.

### Example
```python
policy = Policy.create(limit=10, unwatched=True)
```
```

--------------------------------

### MediaSettings.createVideo(videoQuality)

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/sync.html

Static factory method to create MediaSettings for video sync.

```APIDOC
## MediaSettings.createVideo(videoQuality)

### Description
Creates a MediaSettings object based on the provided video quality value.

### Method
Static method

### Parameters
- **videoQuality** (int) - Required - Video quality value; use VIDEO_QUALITY_* constants.

### Returns
MediaSettings object.

### Raises
- BadRequest: When provided unknown video quality.

### Example
```python
settings = MediaSettings.createVideo(VIDEO_QUALITY_2_MBPS_720p)
```
```

--------------------------------

### isLatest()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/server.html

Checks if the installed Plex Media Server version is the latest available.

```APIDOC
## isLatest()

### Description
Returns True if the installed version of Plex Media Server is the latest.

### Method
GET

### Endpoint
/updater/status

### Parameters
None

### Response
#### Success Response (200)
- **bool** (boolean) - True if the installed version is the latest, False otherwise.

### Response Example
```json
{
  "isLatest": true
}
```
```

--------------------------------

### LibrarySection.search

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Documentation for the LibrarySection.search method, including filter syntax, operators, and examples.

```APIDOC
## LibrarySection.search

### Description
Searches the library section using Plex search filters. Supports advanced filtering with operators and nested and/or trees.

### Method
search

### Parameters
#### Query Parameters
- **filters** (dict) - Optional - A dictionary of filter fields and values. Fields can be prefixed with `libtype.` (e.g., `show.collection`, `episode.title`). Operators can be appended to field names (e.g., `genre&`, `director!`, `title<`, `addedAt<<`).
- **libtype** (str) - Optional - The type of media to search for (e.g., 'episode', 'show').
- **title** (str) - Optional - The title to search for.
- **unwatched** (bool) - Optional - Filter for unwatched items.

### Request Example
```python
library.search(filters={"show.collection": "Documentary", "episode.inProgress": True})
library.search(filters={"artist.genre": "pop", "album.decade": 2000})
showLibrary.search(title="Winter is Coming", libtype='episode')
showLibrary.search(libtype='episode', filters={"episode.title": "Winter is Coming"})
showLibrary.searchEpisodes(title="Winter is Coming")
showLibrary.search(filters={"episode.title": "Winter is Coming"})
showLibrary.search(unwatched=True)
```

### Response
#### Success Response
Returns a list of matching media objects (e.g., Episode, Show, Artist, Album, Track).

### Notes
- Filters can be prefixed with `libtype.` to specify the media type. If no prefix, the default library type is assumed.
- If a filter does not exist for the default type, it falls back to the most specific `libtype` available.
- Operators can be appended to filter fields for granularity. Supported operators depend on the data type.
- The `&` operator can be used to AND together a list of values.
- Advanced filters can be combined into a tree of `and`/`or` branches.

### Examples
```python
# 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})
```
```

--------------------------------

### LibrarySection.settings()

Source: https://python-plexapi.readthedocs.io/en/latest/_modules/plexapi/library.html

Returns a list of all library settings.

```APIDOC
## LibrarySection.settings()

### Description
Returns a list of all library settings.

### Method
LibrarySection.settings

### Returns
List of `Setting` objects.
```

--------------------------------

### MyPlexServerShare.history(maxresults=9999999, mindate=None)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/myplex.html

Get all Play History for a user in this shared server.

```APIDOC
## MyPlexServerShare.history(maxresults=9999999, mindate=None)

### Description
Get all Play History for a user in this shared server.

### Method
history

### Parameters
- **maxresults** (int) - Optional - Only return the specified number of results.
- **mindate** (datetime) - Optional - Min datetime to return results from.

### Response
Returns play history.
```

--------------------------------

### MyPlexUser.history(maxresults=None, mindate=None)

Source: https://python-plexapi.readthedocs.io/en/latest/modules/myplex.html

Get all Play History for a user in all shared servers.

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

### Description
Get all Play History for a user in all shared servers.

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

### Parameters
- **maxresults** (_int_, optional) – Only return the specified number of results.
- **mindate** (_datetime_, optional) – Min datetime to return results from.

### Returns
- **list** – Play history items.

```
Tokens:
Raw