API Documentation¶

Sessions¶

class plexdevices.Session(user=None, password=None, token=None)¶

A Plex session. You can use pickle to save and load existing session objects.

Plex.TV Usage:

>>> import plexdevices
>>> s = plexdevices.Session(user=username, password=password)
>>> s.refresh_devices()
>>> on_deck = s.servers[0].media_container('/library/onDeck')
>>> on_deck.children[0].resolve_url()
http://server/file.mp4?X-Plex-Token=XXXXXXXXXXX

Manual Usage:

>>> import plexdevices
>>> s = plexdevices.Session()
>>> s.manual_add_server('192.168.1.1', 32400)
>>> s.manual_add_server('192.168.1.2', 32400)
>>> s.servers
[<Device:A - Plex Media Server>, <Device:B - Plex Media Server>]

login(password)¶: Retrieve the token for the session user from https://plex.tv/users/sign_in.json.

manual_add_server(address, port=32400, protocol='http', token='')¶

Add a Server to the session.

Parameters:	address – address to the server. e.g. `127.0.0.1`. token – (optional) the `X-Plex-Token` to use when accessing this server.

players = None¶: List of Player‘s accessible by the current user.

refresh_devices()¶: Retrieve the devices for the current user from https://plex.tv/api/resources

refresh_users()¶: Retrieve the Plex Home users from https://plex.tv/api/home/users.

servers = None¶: List of Server‘s accessible by the current user.

switch_user(user_id, pin=None)¶

Switch the current user to the given user id, and refresh the available devices.

Parameters:	user_id – the id of the user. As given from `https://plex.tv/api/home/users`. pin – (optional) the 4-digit PIN code of the user.

users = None¶: List of Plex Home users.

Device Objects¶

Device¶

class plexdevices.Device¶

access_token¶

client_identifier¶

created_at¶

device¶

headers¶

https_required¶

Type:	bool

last_seen_at¶

name¶

owned¶

Type:	bool

platform¶

platform_version¶

presence¶

Type:	bool

product¶

product_version¶

provides¶

Type:	list

public_address_matches¶

Type:	bool

request(endpoint, method='GET', data=None, params=None, headers={}, raw=False, allow_redirects=True)¶

Make an HTTP request to the device.

Parameters:	endpoint – location on server. e.g. `/library/onDeck`. method – (optional) request function. Defaults to `GET`. data – (optional) data to send with the request. Defaults to `None`. params – (optional) params to include in the URL. Defaults to `None`. headers – (optional) additional headers. Defaults to `{}`. raw – (optional) return raw data. Defaults to `False`. allow_redirects – (optional) follow 302 redirects. Defaults to `True`.
Returns:	(HTTP status code, data)
Return type:	Tuple (int, str)

synced¶

Type:	bool

Server¶

class plexdevices.Server¶

A Device which provides a server.

container(endpoint, size=None, page=None, params=None, usejson=True)¶

Parameters:	endpoint – destination on the server. e.g. `/library/onDeck`. size – (optional) the max number of items to retrieve. page – (optional) the page number for paging large containers. params – (optional) Dictionary of parameters to be added to the url in the request.
Returns:	a Dictionary representing a Plex Media Container.
Return type:	Dictionary

image(endpoint, w=None, h=None)¶

If w and h are set, the server will transcode the image to the given size.

Parameters:	endpoint – location of the image. This can also be a full URL of an image not on the server (for easy channel support). w – (optional) width to transcode. h – (optional) height to transcode.
Returns:	Raw data of an image.

media_container(endpoint, size=None, page=None, params=None, usejson=True)¶

Parameters:	endpoint – destination on the server. e.g. `/library/onDeck`. size – (optional) the max number of items to retrieve. page – (optional) the page number for paging large containers. params – (optional) Dictionary of parameters to be added to the url in the request.
Returns:	a `MediaContainer` representing a Plex Media Container.
Return type:	`MediaContainer`

Player¶

class plexdevices.Player¶: A Device which provides a player.

Containers¶

Media Container¶

class plexdevices.MediaContainer¶

An object representing a Plex MediaContainer.

children = None¶: List of BaseObject‘s in the container.

data = None¶: Dictionary of the MediaContainer’s values.

server = None¶: The Server which this container was retrieved from.

Play Queues¶

Inheritance diagram of plexdevices.MediaContainer, plexdevices.PlayQueue

class plexdevices.PlayQueue¶

An object representing a Plex PlayQueue. A PlayQueue is a playlist that is maintained by the server.

When you want to play a Media item, use the create() method. Then during playback, use timeline_update() to let the server know about the players state.

add_item(item, player_headers)¶: Add Media to the PlayQueue.

static create(item, player_headers)¶

Create a PlayQueue on a server and return a PlayQueue object.

Parameters:	item – the `Media` to be the initial item added to the PlayQueue. player_headers – Dictionary of headers identifying the player using the PlayQueue. Must include X-Plex-Client-Identifier and X-Plex-Device-Name.
Returns:	`PlayQueue` object
Return type:	plexdevices.PlayQueue

get_next()¶: Select and return the next MediaItem in the PlayQueue, or None.

get_prev()¶: Select and return the previous MediaItem in the PlayQueue, or None.

remove_item(item)¶: Remove a MediaItem from the PlayQueue.

selected_item¶: The selected MediaItem

timeline_update(item, time, headers, state='playing')¶

Update the timeline. This should be done frequently during playback. The server will update the view offset of the item and handle the watched/unwatched state.

Parameters:	item – the play queue item. time – the current playback time in ms. headers – the players headers. `X-Plex-Client-Identifier`, `X-Plex-Device-Name`. state – playing, stopped, paused

update()¶: Update the PlayQueue‘s data from its server.

Items in Containers¶

Deciding what to do with the items in a container should be done by checking the type with isinstance().

def item_clicked(item):
    if isinstance(item, (plexdevices.Movie, plexdevices.Episode)):
        video_player.play(item.resolve_url())
    elif isinstance(item, Directory):
        next_container = server.media_container(item.key)

Base Objects¶

class plexdevices.BaseObject¶

Abstract base class. The base class of all items in containers.

# generically emit an item in PyQt5
item_selected = pyqtSignal(plexdevices.BaseObject)

class plexdevices.Directory¶

a directory that is used for navigation.

key¶: The endpoint on the server which this object points to. This can be relative or absolute.

title¶

class plexdevices.InputDirectory¶

A special Directory where you should get a string from the user and send it to the key as a query parameter.

if isinstance(item, InputDirectory):
    user_input = get_string()
    next_container = server.media_container(item.key, params={'query': user_input})

class plexdevices.PreferencesDirectory¶: A special Directory used in channels for channel preferences.

Media Directories¶

class plexdevices.MediaDirectory¶

A directory that holds MediaItems. These directories have metadata, can be added to a PlayQueue, and can be marked watched/unwatched. A MediaContainer with its key will contain all the MediaItems.

added_at¶: Unix timestamp.

allow_sync¶

Type:	bool

art¶: Art key.

key¶: The endpoint on the server which this object points to. This can be relative or absolute.

mark_unwatched()¶: Mark this item as unwatched on its server.

mark_watched()¶: Mark this item as watched on its server.

summary¶: Description of the item.

thumb¶: Either the key to the thumb, or None. Use image() to get the image data.

title¶

updated_at¶: Unix timestamp.

PhotoAlbum¶

class plexdevices.PhotoAlbum¶: MediaDirectory with extra metadata for a Photo Album.

Album¶

class plexdevices.Album¶

MediaDirectory with extra metadata for a music Album.

genres¶

Type:	list

originally_available_at¶: Release date.

parent_key¶: Artist key.

parent_title¶: Artist name.

year¶

Artist¶

class plexdevices.Artist¶

MediaDirectory with extra metadata for a music Artist.

country¶

Type:	list

genres¶

Type:	list

Season¶

class plexdevices.Season¶

MediaDirectory with extra metadata for a TV Season.

count¶: Number of episodes.

parent_key¶: Show key.

parent_summary¶: Show summary.

parent_thumb¶: Show thumb.

parent_title¶: Show name.

unwatched_count¶

watched_count¶

Show¶

class plexdevices.Show¶

MediaDirectory with extra metadata for a TV Show.

banner¶

child_count¶: Number of seasons.

count¶: Number of episodes.

duration¶: Length of one episode in ms.

originally_available_at¶: Premiere date.

studio¶

unwatched_count¶

watched_count¶

Media Items¶

class plexdevices.MediaItem¶

An object representing a piece of Media.

added_at¶: Unix timestamp.

allow_sync¶

Type:	bool

art¶: Art key.

in_progress¶: True if the item is in progress.

key¶: The endpoint on the server which this object points to. This can be relative or absolute.

last_viewed_at¶: not always available.

mark_unwatched()¶: Mark this item as unwatched on its server.

mark_watched()¶: Mark this item as watched on its server.

media = None¶: List of Media objects that hold information about the file.

resolve_url()¶: Return the url of the first part regardless of how many there are.

summary¶: Description of the item.

thumb¶: Either the key to the thumb, or None. Use image() to get the image data.

title¶

updated_at¶: Unix timestamp.

view_offset¶: The resume position in ms.

watched¶: True if the item is watched.

year¶

Media¶

class plexdevices.media.Media¶

A Media object represents a single copy of a MediaItem. In most cases, a MediaItem will have a single Media object. If the server has a 480p and a 1080p copy of a movie, there will be two Media objects.

aspect_ratio¶: Aspect ratio as floating point number. e.g. 1.78 for 16:9.

audio_channels¶: Number of audio channels.

audio_codec¶: Audio codec as a string.

bitrate¶

container¶: Container file format. e.g. mkv.

duration¶: Duration in ms.

height¶: Vertical resolution.

id¶

parts = None¶: List of Part objects which references the actual files. Typically there is only one part.

video_codec¶: Video codec as a string.

video_frame_rate¶: Framerate as a string. e.g. 24p, NTSC.

video_profile¶: main, high, ...

video_resolution¶: Vertical resolution as an integer. e.g. 1080

width¶: Horizontal resolution.

Parts¶

class plexdevices.media.Part¶

A part represents an actual file.

container¶: Container file format. e.g. mkv.

duration¶: Duration in ms.

file¶: The path to the file on the server. use the key to actually access it.

id¶

key¶: The key to playing this item. It either points to the file on the server, or to a function on the server that will resolve it to a playable url.

resolve_key()¶: Resolve the key into a url which can be given to a media player.

size¶: Size of the file in bytes.

video_profile¶: main, high, ...

Episode¶

class plexdevices.Episode¶

MediaItem with extra metadata for a TV Show Episode.

duration¶: Duration in ms.

grandparent_key¶: Key of the show.

grandparent_title¶: Title of the show.

index¶: Episode number.

originally_available_at¶: Air date.

parent_index¶: Season number.

parent_key¶: Key of the season.

Movie¶

class plexdevices.Movie¶

MediaItem with extra metadata for a Movie.

duration¶: Duration in ms.

originally_available_at¶

Type:	datetime.date

rating¶: Movie rating as a floating point number.

studio¶

tagline¶

Track¶

class plexdevices.Track¶

MediaItem with extra metadata for a Music Track.

duration¶: Duration in ms.

grandparent_key¶: Artist key.

grandparent_thumb¶

grandparent_title¶: Artist name.

index¶: Track number.

parent_key¶: Album key.

parent_thumb¶

parent_title¶: Album name.

Photo¶

class plexdevices.Photo¶

MediaItem with extra metadata for a Photo.

grandparent_key¶: Key to the folder which holds the photoalbum.

originally_available_at¶

parent_key¶: Key to the album which holds this photo.

Remote¶

class plexdevices.Remote(player, name, port=8000)¶

A remote control for a Plex device.

Usage (subscribe method):

>>> import plexdevices
>>> s = plexdevices.Session(user=username, password=password)
>>> s.refresh_devices()
>>> player = s.players[0]
>>> r = plexdevices.Remote(player=player)
>>> r.timeline_subscribe()
>>> r.down()
>>> r.select()
>>> r.timeline_unsubscribe()

Usage (poll method):

>>> r = plexdevices.Remote(player=player)
>>> r.timeline_poll()
>>> r.down()
>>> r.select()

command(command, params=None)¶: Send a command to the player with optional parameters.

headers¶: Dictionary of the remote’s X-Plex-Client-Identifier and X-Plex-Device-Name.

mirror(plex_object, **kwargs)¶: Send the player to the preplay screen of the given BaseObject.

play_media(media_object)¶: Make the player play the given MediaItem.

timeline()¶: Returns the latest timeline that was POSTed from the player.

timeline_poll()¶: This is an alternative to the subscribe command for controllers that cannot use persistent connections to receive updates from the player.

timeline_post(data)¶: Called whenever the player POSTs the timeline to the remote. Subclass and reimplement to add functionality.

timeline_subscribe()¶: Subscribe to the timeline.

timeline_unsubscribe()¶: Unsubscribe from the timeline.