0
# PlexAPI
1

2
Unofficial Python bindings for the Plex Media Server API. PlexAPI enables developers to interact programmatically with Plex servers for comprehensive media management, remote control of connected clients, real-time server notifications, and advanced search capabilities across all media types.
3

4
## Package Information
5

6
- **Package Name**: PlexAPI
7
- **Language**: Python
8
- **Installation**: `pip install plexapi`
9
- **Documentation**: http://python-plexapi.readthedocs.io/en/latest/
10
- **Repository**: https://github.com/pkkid/python-plexapi
11

12
## Core Imports
13

14
```python
15
from plexapi.server import PlexServer
16
from plexapi.myplex import MyPlexAccount
17
```
18

19
Common imports for media types:
20

21
```python
22
from plexapi.video import Movie, Show, Episode
23
from plexapi.audio import Artist, Album, Track
24
from plexapi.photo import Photo, Photoalbum
25
```
26

27
Client control:
28

29
```python
30
from plexapi.client import PlexClient
31
```
32

33
## Basic Usage
34

35
### Connecting to a Plex Server
36

37
Using MyPlex authentication (recommended):
38

39
```python
40
from plexapi.myplex import MyPlexAccount
41

42
# Connect using MyPlex credentials
43
account = MyPlexAccount('username', 'password')
44
plex = account.resource('My Server Name').connect()
45
```
46

47
Direct server connection with token:
48

49
```python
50
from plexapi.server import PlexServer
51

52
# Connect directly with server details
53
baseurl = 'http://plexserver:32400'
54
token = '2ffLuB84dqLswk9skLos'
55
plex = PlexServer(baseurl, token)
56
```
57

58
### Basic Media Operations
59

60
```python
61
# List unwatched movies
62
movies = plex.library.section('Movies')
63
for movie in movies.search(unwatched=True):
64
    print(movie.title)
65

66
# Mark a TV show as watched
67
show = plex.library.section('TV Shows').get('Game of Thrones')
68
show.markWatched()
69

70
# Search across all libraries
71
for item in plex.search('Game'):
72
    print(f'{item.title} ({item.TYPE})')
73
```
74

75
### Client Control
76

77
```python
78
# List connected clients
79
for client in plex.clients():
80
    print(client.title)
81

82
# Play media on a client
83
cars = plex.library.section('Movies').get('Cars')
84
client = plex.client("Michael's iPhone")
85
client.playMedia(cars)
86
```
87

88
## Architecture
89

90
PlexAPI follows the Plex XML API structure with camelCase naming conventions to match the official API. The library is organized around several key components:
91

92
- **Authentication Layer**: MyPlexAccount for cloud authentication, direct PlexServer connection
93
- **Library Hierarchy**: Library → Sections → Media Items with comprehensive navigation
94
- **Media Objects**: Strongly-typed objects for Movies, Shows, Episodes, Artists, Albums, Tracks, Photos
95
- **Client Control**: Remote control interface for all connected Plex clients including Sonos speakers
96
- **Real-time Events**: AlertListener for server notifications and status monitoring
97
- **Utilities**: Helper functions for downloads, search, metadata management, and sync operations
98

99
## Capabilities
100

101
### Server Connection and Authentication
102

103
Core functionality for connecting to Plex servers using MyPlex cloud authentication or direct server tokens. Handles server discovery, resource enumeration, and connection management.
104

105
```python { .api }
106
class PlexServer:
107
    def __init__(self, baseurl=None, token=None, session=None, timeout=None): ...
108

109
class MyPlexAccount:
110
    def __init__(self, username=None, password=None, token=None, session=None, timeout=None): ...
111
    def resource(self, name): ...
112
    def resources(self): ...
113
```
114

115
[Server Connection and Authentication](./server-connection.md)
116

117
### Library Management and Media Browsing
118

119
Comprehensive library section management with support for Movies, TV Shows, Music, and Photos. Provides powerful search, filtering, and navigation capabilities across all media types.
120

121
```python { .api }
122
class Library:
123
    def sections(self): ...
124
    def section(self, title): ...
125
    def search(self, title=None, libtype=None, **kwargs): ...
126
    def onDeck(self): ...
127
    def recentlyAdded(self): ...
128

129
class LibrarySection:
130
    def all(self): ...
131
    def get(self, title): ...
132
    def search(self, **kwargs): ...
133
    def refresh(self): ...
134
```
135

136
[Library Management and Media Browsing](./library-management.md)
137

138
### Media Objects and Metadata
139

140
Strongly-typed media objects for all content types including Movies, TV Shows, Episodes, Artists, Albums, Tracks, and Photos. Each object provides full metadata access and media-specific operations.
141

142
```python { .api }
143
class Movie:
144
    def play(self): ...
145
    def download(self, savepath=None, **kwargs): ...
146
    def markWatched(self): ...
147
    def rate(self, rating): ...
148

149
class Show:
150
    def episodes(self): ...
151
    def seasons(self): ...
152
    def season(self, title): ...
153

154
class Track:
155
    def play(self): ...
156
    def artist(self): ...
157
    def album(self): ...
158
```
159

160
[Media Objects and Metadata](./media-objects.md)
161

162
### Client Control and Remote Playback
163

164
Remote control interface for all connected Plex clients including smartphones, tablets, streaming devices, and Sonos speakers. Supports playback control, volume adjustment, and timeline navigation.
165

166
```python { .api }
167
class PlexClient:
168
    def playMedia(self, media, **kwargs): ...
169
    def pause(self): ...
170
    def play(self): ...
171
    def stop(self): ...
172
    def skipNext(self): ...
173
    def seekTo(self, offset): ...
174
    def timeline(self): ...
175
```
176

177
[Client Control and Remote Playback](./client-control.md)
178

179
### Playlists and Playback Queues
180

181
Playlist creation, management, and playback queue operations. Supports both audio and video playlists with full CRUD operations and queue manipulation.
182

183
```python { .api }
184
class Playlist:
185
    def items(self): ...
186
    def addItems(self, items): ...
187
    def removeItems(self, items): ...
188
    def play(self, client=None): ...
189

190
class PlayQueue:
191
    def addItem(self, item): ...
192
    def removeItem(self, item): ...
193
    def refresh(self): ...
194
```
195

196
[Playlists and Playback Queues](./playlists.md)
197

198
### Media Streaming and Transcoding
199

200
Media file information, streaming details, and transcoding management. Provides access to media parts, streams, quality settings, and active transcoding sessions.
201

202
```python { .api }
203
class Media:
204
    def parts(self): ...
205

206
class MediaPart:
207
    def streams(self): ...
208

209
class VideoStream:
210
    # Video stream properties and methods
211

212
class TranscodeSession:
213
    # Transcoding session management
214
```
215

216
[Media Streaming and Transcoding](./media-streaming.md)
217

218
### Settings and Server Management
219

220
Server settings access, sync operations, and utility functions. Includes configuration management, mobile sync capabilities, and helper functions for common operations.
221

222
```python { .api }
223
class Settings:
224
    def get(self, attr): ...
225
    def save(self): ...
226

227
class SyncItem:
228
    # Sync item management
229

230
# Utility functions
231
def download(url, token, filename=None, **kwargs): ...
232
def searchType(libtype): ...
233
```
234

235
[Settings and Server Management](./settings-utilities.md)