Python-PlexAPI

https://python-plexapi.readthedocs.io/en/latest/
Admin
Unofficial Python bindings for the Plex API offering library navigation, media control, server...
Tokens:351,740
Snippets:2,995
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install websocket-client

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

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

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

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

### Install Update

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

Initiates the automatic installation of the newest Plex Media Server version.

```APIDOC
## Install Update

### Description
Initiates the automatic installation of the newest Plex Media Server version.

### Method
PUT

### Endpoint
/updater/apply

### Response
#### Success Response (200)
Returns an empty response upon successful initiation of the update installation.

#### Response Example
```json
{}
```
```

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

### Start Alert Listener

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

Creates a websocket connection to the Plex Server to receive notifications. Requires the 'websocket-client' library to be installed.

```python
from plexapi.server import PlexServer
from plexapi.alert import AlertListener

PLEX_URL = 'YOUR_PLEX_URL'
PLEX_TOKEN = 'YOUR_PLEX_TOKEN'

p = PlexServer(PLEX_URL, PLEX_TOKEN)

def on_message(message):
    print(f"Received message: {message}")

def on_error(error):
    print(f"Received error: {error}")

notifier = p.startAlertListener(callback=on_message, callbackError=on_error)

# Keep the script running to listen for alerts
# import time
# time.sleep(3600) # Listen for 1 hour
# notifier.stop()
```

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

### Start Playback

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

Start playback for a specified media type. Defaults to 'video' if not specified.

```python
plexapi.client.Client.play(mtype='music')
```

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

### Install plexapi

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

Install the base plexapi package using pip.

```bash
pip install plexapi
```

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

### Install plexapi with extra features

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

Install plexapi with optional dependencies for specific features like alerts or 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
```

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

### GDM Discovery Socket Setup

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

Demonstrates the socket setup for sending GDM discovery messages, including multicast TTL and broadcast options.

```python
import socket
import struct

gdm_msg = 'M-SEARCH * HTTP/1.0'.encode('ascii')
gdm_timeout = 1

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.settimeout(gdm_timeout)

sock.setsockopt(socket.IPPROTO_IP,
                socket.IP_MULTICAST_TTL,
                struct.pack("B", gdm_timeout))

# For client discovery:
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
gdm_ip = '255.255.255.255'
gdm_port = 32412

# For server discovery:
gdm_ip = '239.0.0.250'
gdm_port = 32414

sock.sendto(gdm_msg, (gdm_ip, gdm_port))

# ... socket receive logic ...

sock.close()
```

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

### play

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

Start playback on the specified Plex client.

```APIDOC
## play

### Description
Start playback on the specified client.

### Parameters
#### Path Parameters
- **client** (PlexClient) - Client to start playing on.

### Method
Not specified (assumed to be part of an object method call)

### Endpoint
Not specified
```

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

### run

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

Starts the thread which monitors the PIN login state.

```APIDOC
## run

### Description
Starts the thread which monitors the PIN login state.

### Parameters
#### Query Parameters
- **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.
```

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

### GDM Server Entry Example

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

Example structure of a discovered GDM server entry. This dictionary contains 'data' with server details and 'from' indicating the source address.

```python
[{'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)}]
```

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

### Install Plex Media Server Update

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

Initiates the automatic installation of the newest Plex Media Server version. Note that this may sometimes require user interaction via a GUI.

```python
plex.installUpdate()
```

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

### Start Plex PIN Login Monitor

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

Starts a thread to monitor the PIN login state. A callback can be provided to receive the authentication token. The timeout defaults to 120 seconds.

```python
run(_callback =None_, _timeout =120_)
```

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

### GDM Client Entry Example

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

Example structure of a discovered GDM client entry. This dictionary includes 'data' with client details and 'from' indicating the source address.

```python
[{'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)}]
```

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

### Start Playback

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

Starts or resumes playback for the specified media type. You can specify 'music', 'photo', or 'video' as the media type.

```APIDOC
## play

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

### Method
`play(mtype='video')`

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

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

### Start PIN Login Monitoring Thread

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

Starts a background thread to monitor the PIN login state. This is used for device linking. A callback can be provided to receive the authentication token upon successful login.

```python
def on_login(token):
    print(f'Login successful: {token}')

plex = MyPlexJWTLogin()
plex.run(callback=on_login, timeout=60)
print(f'Please go to https://plex.tv/link and enter PIN: {plex.pin}')
```

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

### Get Video GUIDs

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

Retrieve a list of globally unique identifiers (GUIDs) for the video. This property is cached.

```python
@cached_data_property
    def guids(self):
        return self.findItems(self._data, media.Guid)
```

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

### Syncing Media to a Device

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

Complete example demonstrating how to set up and initiate a sync operation for media to a specified Plex client device.

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

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

### canInstallUpdate

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

Checks if the newest version of Plex Media Server can be installed automatically on the current system.

```APIDOC
## canInstallUpdate

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

### Method
canInstallUpdate
```

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

### Get Album GUIDs

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

Lazily loads and returns a list of GUID objects for the album. Uses cached data for efficiency.

```python
@cached_data_property
def guids(self):
    return self.findItems(self._data, media.Guid)
```

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

### Initiate a Sync Job

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

Example of setting up and initiating a sync job for a Plex library section to a specified client device. Requires importing sync-related classes and account/server connections.

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

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

### playMedia

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

Starts playback of a specified media item, with options for offset and additional parameters.

```APIDOC
## playMedia

### Description
Start playback of the specified media item.

### Method
POST

### Endpoint
/player/playback/playMedia

### Parameters
#### Query Parameters
- **media** (:class:`~plexapi.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 additional parameters to include in the playback request. See also: https://github.com/plexinc/plex-media-player/wiki/Remote-control-API#modified-commands
```

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

### Get Collection Metadata Directory Path

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

Returns the file system path to the metadata directory for a collection, based on its GUID.

```python
    @property
    def metadataDirectory(self):
        """ Returns the Plex Media Server data directory where the metadata is stored. """
        guid_hash = utils.sha1hash(self.guid)
        return str(Path('Metadata') / 'Collections' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### PlexServer Initialization with Configuration

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

Initializes the PlexServer using configuration values for server base URL and token if not provided directly. Includes session and timeout setup.

```python
def __init__(self, baseurl=None, token=None, session=None, timeout=None):
    self._baseurl = baseurl or CONFIG.get('auth.server_baseurl', 'http://localhost:32400')
    self._baseurl = self._baseurl.rstrip('/')
    self._token = logfilter.add_secret(token or CONFIG.get('auth.server_token'))
    self._showSecrets = CONFIG.get('log.show_secrets', '').lower() == 'true'
    self._session = session or requests.Session()
    self._timeout = timeout or TIMEOUT
    data = self.query(self.key, timeout=self._timeout)
    super(PlexServer, self).__init__(self, data, self.key)
```

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

### Initialize PlexServer with URL and Token

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

Connect to your Plex Media Server using its base URL and authentication token. Ensure you have your token ready before initializing.

```python
from plexapi.server import PlexServer

# Replace with your actual Plex URL and token
PLEXURL = 'YOUR_PLEX_URL'
TOKEN = 'YOUR_PLEX_TOKEN'

plex = PlexServer(PLEXURL, TOKEN)
```

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

### Get Photo Metadata Directory

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

Returns the path to the directory where photo metadata is stored on the Plex Media Server, based on the photo's GUID.

```python
@property
def metadataDirectory(self):
    """ Returns the Plex Media Server data directory where the metadata is stored. """
    guid_hash = utils.sha1hash(self.parentGuid)
    return str(Path('Metadata') / 'Photos' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Initialize PlexServer

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

Instantiate the PlexServer class with the server's base URL and authentication token. It handles default values and session setup.

```python
plex = PlexServer(baseurl, token)
```

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

### Get Plex Claim Token

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

Retrieves a new claim token for registering a Plex Server instance to your account. Useful for automated server setup.

```python
response = self._session.get('https://plex.tv/api/claim/token.json', headers=self._headers(), timeout=TIMEOUT)
        if response.status_code not in (200, 201, 204):  # pragma: no cover
            codename = codes.get(response.status_code)[0]
            errtext = response.text.replace('
', ' ')
            raise BadRequest(f'({response.status_code}) {codename} {response.url}; {errtext}')
        return response.json()['token']
```

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

### GDM Server Discovery Example

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

Scans the network for Plex Media Servers. Requires no arguments.

```python
from plexapi.gdm import GDM
from pprint import pprint

gdm = GDM()
gdm.scan()
pprint(gdm.entries)
```

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

### Get Metadata Directory Path

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

Calculates and returns the path to the metadata directory for a TV show based on its GUID. This is used internally by Plex Media Server.

```python
@property
def metadataDirectory(self):
    """ Returns the Plex Media Server data directory where the metadata is stored. """
    guid_hash = utils.sha1hash(self.guid)
    return str(Path('Metadata') / 'TV Shows' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### PlexClient Initialization and Connection

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

This section details the initialization parameters for the PlexClient class and how to establish a connection to a Plex client. It covers direct connection to a client's base URL or proxying commands through a Plex Server.

```APIDOC
## PlexClient

### Description
Main class for interacting with a Plex client. This class can connect directly to the client and control it or proxy commands through your Plex Server. Refer to the Plex client API documentation for more details.

### Parameters
- **server** (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional).
- **data** (ElementTree): Response from PlexServer used to build this object (optional).
- **initpath** (str): Path used to generate data.
- **baseurl** (str): HTTP URL to connect directly to this client.
- **identifier** (str): The resource/machine identifier for the desired client. May be necessary when connecting to a specific proxied client (optional).
- **token** (str): X-Plex-Token used for authentication (optional).
- **connect** (bool): Whether to connect to the client upon initialization (default True).
- **session** (:class:`~requests.Session`): requests.Session object if you want more control (optional).
- **timeout** (int): timeout in seconds on initial connect to client (default config.TIMEOUT).
- **parent** (obj): Weak reference to a parent object (optional).

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

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

- **timeout** (int): timeout in seconds on initial connect to client (optional).

**Raises:**
- **Unsupported**: If the object was not built from a URL and cannot be reloaded.
```

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

### Get On Deck Items

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

Retrieves a list of media items that are currently on deck within a specific library section. This is useful for quickly accessing recently started or unfinished content.

```python
def onDeck(self):
    """ Returns a list of media items on deck from this library section. """
    key = self._buildQueryKey(f'/library/sections/{self.key}/onDeck')
    return self.fetchItems(key)
```

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

### Initialize MyPlexAccount

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

Import the MyPlexAccount class to begin interacting with your Plex account.

```python
from plexapi.myplex import MyPlexAccount
```

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

### Get Video Metadata Directory Path

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

Returns the path to the Plex Media Server data directory where metadata for a video is stored. This is determined by hashing the video's GUID.

```python
def metadataDirectory(self):
    """ Returns the Plex Media Server data directory where the metadata is stored. """
    guid_hash = utils.sha1hash(self.grandparentGuid)
    return str(Path('Metadata') / 'TV Shows' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Get Metadata Directory Path

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

Constructs the path to the Plex Media Server data directory where metadata for the video is stored. It uses a SHA1 hash of the video's GUID.

```python
guid_hash = utils.sha1hash(self.guid)
return str(Path('Metadata') / 'Movies' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Create Sync Item with Media Settings

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

Demonstrates how to create a sync item for a library section with specific media settings. This is useful for setting up offline playback for media.

```python
from plexapi.sync import SyncItem
from plexapi.settings import MediaSettings
from plexapi.const import VIDEO_QUALITY_3_MBPS_720p

media_settings = MediaSettings.create(VIDEO_QUALITY_3_MBPS_720p)
section.sync(target, policy, media_settings, title='Next best movie', sort='rating:desc')
```

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

### Get Playlist Metadata Directory Path

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

Returns the path to the Plex Media Server data directory where the playlist metadata is stored. Uses SHA1 hashing of the playlist GUID.

```python
guid_hash = utils.sha1hash(self.guid)
return str(Path('Metadata') / 'Playlists' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Get Photo Metadata Directory Path

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

Retrieves the file system path on the Plex Media Server where the photo's metadata is stored. This is derived from the photo's GUID.

```python
photo.metadataDirectory
```

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

### Starting Playback on a Client

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

Initiates playback of the media item on a specified Plex client. Requires a `PlexClient` object to be passed as an argument.

```python
play(_client_)
```

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

### Connect to Plex Server and Switch User

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

Establishes a connection to the Plex server using the admin token and demonstrates how to switch to a different user account.

```python
plex = PlexServer('http://plexserver:32400', token='2ffLuB84dqLswk9skLos')
userPlex = plex.switchUser("Username")
```

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

### Get Media Item by GUID

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

Retrieve a media item using its external Plex, IMDB, TMDB, or TVDB ID. This method is only supported for Plex Movie and Plex TV Series agents.

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

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

### Getting Metadata Directory Path for Audio Track

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

Returns the path to the Plex Media Server data directory where the metadata for the audio track is stored. It generates a hash from the track's GUID.

```python
def metadataDirectory(self):
        """ Returns the Plex Media Server data directory where the metadata is stored. """
        guid_hash = utils.sha1hash(self.parentGuid)
        return str(Path('Metadata') / 'Albums' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Initialize PlexServer with MyPlex Account

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

Connect to your Plex Media Server by first authenticating with your Plex account. This is useful if you don't know your server's direct URL or token.

```python
from plexapi.myplex import MyPlexAccount

# Replace with your Plex username and password
PLEX_USERNAME = 'YOUR_PLEX_USERNAME'
PLEX_PASSWORD = 'YOUR_PLEX_PASSWORD'

account = MyPlexAccount(PLEX_USERNAME, PLEX_PASSWORD)
plex = account.resource('YourServerName').connect()  # Replace 'YourServerName' with your server's name
```

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

### Get Clip Metadata Directory Path

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

Returns the Plex Media Server data directory path for a clip's metadata. It uses a SHA1 hash of the clip's GUID to construct the path.

```python
@property
def metadataDirectory(self):
    """ Returns the Plex Media Server data directory where the metadata is stored. """
    guid_hash = utils.sha1hash(self.guid)
    return str(Path('Metadata') / 'Movies' / guid_hash[0] / f'{guid_hash[1:]}.bundle')
```

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

### Guid

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

Represents a single Guid media tag. It inherits from PlexObject and has TAG set to 'Guid'.

```APIDOC
## Class plexapi.media.Guid

### Description
Represents a single Guid media tag.

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

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

### Start Playback on a Client

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

Initiates playback of the media item on a specified Plex client. Requires a valid PlexClient object.

```python
def play(self, client):
    """ Start playback on the specified client.

        Parameters:
            client (:class:`~plexapi.client.PlexClient`): Client to start playing on.
    """
    client.playMedia(self)
```

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

### PlexObject Initialization Parameters

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

Illustrates the parameters used when initializing a PlexObject, including the server connection, XML data, initialization path, and parent object.

```python
def __init__(self, server, data, initpath=None, parent=None):
    self._server = server
    self._data = data
    self._initpath = initpath or self.key
    self._parent = weakref.ref(parent) if parent is not None else None
    self._details_key = None

    # Allow overwriting previous attribute values with `None` when manually reloading
    self._overwriteNone = True
    # Automatically reload the object when accessing a missing attribute
    self._autoReload = CONFIG.get('plexapi.autoreload', True, bool)
    # Attribute to save batch edits for a single API call
    self._edits = None

    if data is not None:
        self._loadData(data)
    self._details_key = self._buildDetailsKey()
```

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

### Guid

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

Represents a single Guid library media tag. Guid tags have a specific TAGTYPE of 314.

```APIDOC
## Class Guid

### Description
Represents a single Guid library media tag.

### Attributes
- **TAGTYPE** (int): 314
```

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

### Chained Method Example

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

Demonstrates chaining multiple methods to manage a managed hub. Use this to perform a sequence of hub modifications.

```python
managedHub.promoteRecommended().promoteHome().demoteShared().reload()
```

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

### Check if Plex Media Server Update Can Be Installed

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

Checks if the newest Plex Media Server version can be installed automatically. This is typically true for desktop installations (Windows, Mac) but false for containerized or NAS installations.

```python
can_install = plex.canInstallUpdate()
print(f"Can Plex Media Server update automatically? {can_install}")
```

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

### Guid

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

Represents a single Guid media tag.

```APIDOC
## Guid

### Description
Represents a single Guid media tag.

### Attributes
- **TAG** (str): 'Guid'
- **id** (id): The guid for external metadata sources (e.g. IMDB, TMDB, TVDB, MBID).
```

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

### Import PlexServer

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

Import the PlexServer class to establish a connection to your Plex Media Server.

```python
from plexapi.server import PlexServer

```

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

### Create a Regular Collection

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

Demonstrates how to create a regular collection by specifying a title, the target library section, and a list of media items.

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

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

### GDM Client Discovery Example

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

Scans the network for Plex clients. Pass `scan_for_clients=True` to the scan method.

```python
from plexapi.gdm import GDM
from pprint import pprint

gdm = GDM()
gdm.scan(scan_for_clients=True)
pprint(gdm.entries)
```

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

### PlexServer Initialization and Properties

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

This section details how to initialize the PlexServer object and lists its accessible properties, which provide information about the server's status, configuration, and capabilities.

```APIDOC
## PlexServer Class

This is the main entry point to interacting with a Plex server. It allows you to list connected clients, browse your library sections and perform actions such as emptying trash. If you do not know the auth token required to access your Plex server, or simply want to access your server with your username and password, you can also create an PlexServer instance from `MyPlexAccount`.

### Parameters

* **baseurl** (_str_) – Base url for to access the Plex Media Server (default: ‘http://localhost:32400’).
* **token** (_str_) – Required Plex authentication token to access the server.
* **session** (_requests.Session_ _,__optional_) – Use your own session object if you want to cache the http responses from the server.
* **timeout** (_int_ _,__optional_) – Timeout in seconds on initial connection to the server (default config.TIMEOUT).

### Properties

* **allowCameraUpload** (_bool_) – True if server allows camera upload.
* **allowChannelAccess** (_bool_) – True if server allows channel access (iTunes?).
* **allowMediaDeletion** (_bool_) – True is server allows media to be deleted.
* **allowSharing** (_bool_) – True is server allows sharing.
* **allowSync** (_bool_) – True is server allows sync.
* **backgroundProcessing** (_bool_) – Unknown
* **certificate** (_bool_) – True if server has an HTTPS certificate.
* **companionProxy** (_bool_) – Unknown
* **diagnostics** (_bool_) – Unknown
* **eventStream** (_bool_) – Unknown
* **friendlyName** (_str_) – Human friendly name for this server.
* **hubSearch** (_bool_) – True if Hub Search is enabled. I believe this is enabled for everyone
* **machineIdentifier** (_str_) – Unique ID for this server (looks like an md5).
* **multiuser** (_bool_) – True if multiusers are enabled.
* **myPlex** (_bool_) – Unknown (True if logged into myPlex?).
* **myPlexMappingState** (_str_) – Unknown (ex: mapped).
* **myPlexSigninState** (_str_) – Unknown (ex: ok).
* **myPlexSubscription** (_bool_) – True if you have a myPlex subscription.
* **myPlexUsername** (_str_) – Email address if signed into myPlex (user@example.com)
* **ownerFeatures** (_list_) – List of features allowed by the server owner. This may be based on your PlexPass subscription. Features include: camera_upload, cloudsync, content_filter, dvr, hardware_transcoding, home, lyrics, music_videos, pass, photo_autotags, premium_music_metadata, session_bandwidth_restrictions, sync, trailers, webhooks (and maybe more).
* **photoAutoTag** (_bool_) – True if photo auto-tagging is enabled.
* **platform** (_str_) – Platform the server is hosted on (ex: Linux)
* **platformVersion** (_str_) – Platform version (ex: ‘6.1 (Build 7601)’, ‘4.4.0-59-generic’).
* **pluginHost** (_bool_) – Unknown
* **readOnlyLibraries** (_bool_) – Unknown
* **requestParametersInCookie** (_bool_) – Unknown
* **streamingBrainVersion** (_bool_) – Current Streaming Brain version.
* **sync** (_bool_) – True if syncing to a device is enabled.
* **transcoderActiveVideoSessions** (_int_) – Number of active video transcoding sessions.
* **transcoderAudio** (_bool_) – True if audio transcoding audio is available.
* **transcoderLyrics** (_bool_) – True if audio transcoding lyrics is available.
* **transcoderPhoto** (_bool_) – True if audio transcoding photos is available.
* **transcoderSubtitles** (_bool_) – True if audio transcoding subtitles is available.
* **transcoderVideo** (_bool_) – True if audio transcoding video is available.
* **transcoderVideoBitrates** (_bool_) – List of video bitrates.
* **transcoderVideoQualities** (_bool_) – List of video qualities.
* **transcoderVideoResolutions** (_bool_) – List of video resolutions.
* **updatedAt** (_int_) – Datetime the server was updated.
* **updater** (_bool_) – Unknown
* **version** (_str_) – Current Plex version (ex: 1.3.2.3112-1751929)
* **voiceSearch** (_bool_) – True if voice search is enabled. (is this Google Voice search?)
* **_baseurl** (_str_) – HTTP address of the client.
* **_token** (_str_) – Token used to access this client.
* **_session** (_obj_) – Requests session object used to access this client.

### Related Properties

* **library**: Library to browse or search your media.
* **settings**: Returns a list of all server settings.
* **activities**: Returns a list of activities.
```

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

### Can Install Update

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

Checks if the newest Plex Media Server version can be installed automatically by the system.

```APIDOC
## Can Install Update

### Description
Checks if the newest Plex Media Server version can be installed automatically by the system.

### Method
GET

### Endpoint
/updater/status

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

#### Response Example
```json
true
```
```

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

### Guid PlexObject

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

Represents a GUID media tag. It inherits from PlexObject and has an 'id' attribute for external metadata identifiers.

```python
@utils.registerPlexObject
class Guid(PlexObject):
    """ Represents a single Guid media tag.

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

    def _loadData(self, data):
        """ Load attribute values from Plex XML response. """
        self.id = data.attrib.get('id')
```

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

### Access GUIDs for Common Items

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

Retrieves a list of GUID objects associated with common media items. This is a cached property.

```python
    @cached_data_property
    def guids(self):
        return self.findItems(self._data, media.Guid)
```

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

### settings

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

Returns a list of all library settings.

```APIDOC
## settings

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

### Method
settings()
```

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

### Unified Playlist Creation Method

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

A unified method to create playlists, handling regular, smart, and M3U imports based on provided arguments. Raises BadRequest for invalid configurations.

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

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

### Navigate Client Context Menu

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

Opens the context menu on the Plex client.

```python
def contextMenu(self):
        """ Open the context menu on the client. """
        self.sendCommand('navigation/contextMenu')
```

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

### Initialize Plex as a Sync Target

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

Configure PlexAPI to act as a sync target. This involves setting specific headers and platform/device information to mimic a client device like an iPhone.

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

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

### Search for an item by GUID

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

Search for a specific media item on your Plex server using its GUID and type. This is useful for retrieving an exact match.

```python
result = plex.library.search(guid=item.guid, libtype=item.type)
```

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

### Get Public IP Address

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

Retrieve your public IP address using the Plex API. This is a simple GET request to a Plex endpoint.

```python
plex = MyPlexAccount('your-plex-username', 'your-plex-password')
print(plex.publicIP())
```

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

### goToHome

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

Go directly to the home screen of the Plex client.

```APIDOC
## goToHome

### Description
Go directly to the home screen of the Plex client.

### Method
POST

### Endpoint
/navigation/home

### Parameters
None

### Response
#### Success Response (200)
- **response** (xml) - The XML response from the Plex client.

### Error Handling
- **plexapi.exceptions.Unsupported**: When the client doesn't support this capability.
```

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

### Create GUID Lookup Dictionary

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

Builds a dictionary for efficient lookup of library items using their GUIDs. This can speed up performance when frequently accessing items by their unique identifiers.

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

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

### Batch Multi-Editing Example

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

Demonstrates how to select multiple movie items and prepare them for batch editing. This method is designed for efficiency by enabling batch multi-editing mode.

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

```

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

### Create a Regular Playlist

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

Creates a new regular playlist with specified items. Requires a server connection and a list of media items.

```python
cls._create(server, title, items)
```

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

### Building Plex Web URL for Audio Track Details

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

Constructs the Plex Web URL to view the details of the audio track. It uses the server's buildWebURL method with the track's parent key.

```python
def _getWebURL(self, base=None):
        """ Get the Plex Web URL with the correct parameters. """
        return self._server._buildWebURL(base=base, endpoint='details', key=self.parentKey)
```

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

### Build Details Key with XML Include Parameters

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

Constructs a Plex API details key, including specified parameters for filtering or expanding data. Handles includes and excludes based on class attributes.

```python
    def _buildDetailsKey(self, **kwargs):
        """ Builds the details key with the XML include parameters.
            All parameters are included by default with the option to override each parameter
            or disable each parameter individually by setting it to False or 0.
        """
```

```python
        details_key = self.key
        params = {}

        if details_key and hasattr(self, '_INCLUDES'):
            for k, v in self._INCLUDES.items():
                value = kwargs.pop(k, v)
                if value not in [False, 0, '0']:
                    params[k] = 1 if value is True else value

        if details_key and hasattr(self, '_EXCLUDES'):
            for k, v in self._EXCLUDES.items():
                value = kwargs.pop(k, None)
                if value is not None:
                    params[k] = 1 if value is True else value

        if params:
            details_key += '?' + urlencode(sorted(params.items()))
        return details_key
```

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

### Start Plex PIN Login Monitoring Thread

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

Starts a background thread to monitor the state of a PIN-based Plex login. It can optionally call a callback function with the authentication token upon successful login.

```python
from plexapi.myplex import MyPlexPinLogin
import threading

# Assuming 'login' is an instance of MyPlexPinLogin
# def my_callback(token):
#     print(f"Login successful with token: {token}")
# 
# try:
#     login.run(callback=my_callback, timeout=60)
# except RuntimeError as e:
#     print(f"Error starting login thread: {e}")
```

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

### Create MyPlex Device with Headers

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

Creates a new MyPlexDevice, requiring either a provided X-Plex-Client-Identifier in headers or generating one. It then links the device to the account using a PIN login flow and returns the newly created device.

```python
from plexapi.myplex import MyPlexPinLogin

if not headers:
    client_identifier = generateUUID()
    headers = {'X-Plex-Client-Identifier': client_identifier}
    print(f'No X-Plex-Client-Identifier provided, generated: {client_identifier}')
elif 'X-Plex-Client-Identifier' not in headers:
    raise BadRequest('The X-Plex-Client-Identifier header is required.')

clientIdentifier = headers['X-Plex-Client-Identifier']

pinlogin = MyPlexPinLogin(headers=headers)
pinlogin.run(timeout=timeout)
account.link(pinlogin.pin)
pinlogin.waitForLogin()

return account.device(clientId=clientIdentifier)
```

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

### get

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

Alias to :func:`~plexapi.playlist.Playlist.item`.

```APIDOC
## get

### Description
An alias for the `item` method, used to retrieve a specific item from the playlist by its title.

### Method
N/A (Instance Method)

### Endpoint
N/A

### Parameters
- **title** (str) - Required - The title of the item to find within the playlist.

### Response
- **item** (object) - The playlist item object that matches the provided title.

### Raises
- :class:`plexapi.exceptions.NotFound`: When an item with the specified title is not found in the playlist.
```

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

### init_sync()

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

Initializes the PlexAPI sync module by setting necessary headers and platform/device information to enable sync-target functionality.

```APIDOC
## init_sync()

### Description
Initializes the PlexAPI sync module by setting necessary headers and platform/device information to enable sync-target functionality. This is required to use your app as a sync-target.

### Method
```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
```

### Notes
Platform/device/model must be faked because transcoding profiles are hardcoded in Plex. Explicitly specify that your app supports sync-target.
```

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

### playMedia

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

Starts playback of a specified media item on a Sonos speaker. This method allows for controlling playback of movies, music, photos, playlists, and playqueues, with an option to specify an offset to start playback from a particular point in the media.

```APIDOC
## playMedia

### Description
Start playback of the specified media item on a Sonos speaker.

### Method
POST

### Endpoint
/player/playback/play

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **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 - 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
```json
{
  "media": "<Media object>",
  "offset": 0,
  "params": {}
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

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

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

### Example PlexAPI Configuration File

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

This INI file demonstrates all possible configuration options for the Python PlexAPI library, including settings for authentication, headers, and logging. It can be placed at `~/.config/plexapi/config.ini` or a custom path specified by the `PLEXAPI_CONFIG_PATH` environment variable.

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

```

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

### Using Advanced Filters with AND/OR Logic

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

Demonstrates how to combine multiple filters using 'and' and 'or' logic to mimic complex Plex Web advanced filters.

```python
advancedFilters = {
    'and': [
        {
            'or': [
                {'title': 'elephant'},
                {'title': 'bunny'}
            ]
        },
        {'year>>': 1990},
        {'unwatched': True}
    ]
}
library.search(filters=advancedFilters)
```

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

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

### Parameters
#### Path Parameters
- **guid** (str) - Required - The guid to hash.
```

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

### Create Video Sync Settings

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

Returns a MediaSettings object for synchronized video based on video quality. Use predefined constants for video quality.

```python
MediaSettings.createVideo(VIDEO_QUALITY_ORIGINAL)
MediaSettings.createVideo(VIDEO_QUALITY_0_2_MBPS)
```

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

### get

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

Retrieves a media item from the library by its title.

```APIDOC
## get

### Description
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.
```

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

### contextMenu

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

Open the context menu on the client.

```APIDOC
## contextMenu

### Description
Open the context menu on the client.

### Method
POST

### Endpoint
/navigation/contextMenu

### Parameters
None

### Response
#### Success Response (200)
- **response** (xml) - The XML response from the Plex client.

### Error Handling
- **plexapi.exceptions.Unsupported**: When the client doesn't support this capability.
```
Tokens:
Raw