0
# Library Management and Media Browsing
1
2
Comprehensive library section management with support for Movies, TV Shows, Music, and Photos. Provides powerful search, filtering, and navigation capabilities across all media types with section-specific operations and metadata management.
3
4
## Capabilities
5
6
### Library - Main Library Container
7
8
Top-level container for all media sections in a Plex server, providing unified access and cross-section operations.
9
10
```python { .api }
11
class Library:
12
@property
13
def key(self):
14
"""API key path: '/library'"""
15
16
def sections(self):
17
"""
18
List all media sections in the library.
19
20
Returns:
21
List[LibrarySection]: All library sections (MovieSection, ShowSection, MusicSection, PhotoSection)
22
"""
23
24
def section(self, title):
25
"""
26
Get a specific library section by title.
27
28
Args:
29
title (str): Section title to find
30
31
Returns:
32
LibrarySection: Matching section
33
34
Raises:
35
NotFound: If section title not found
36
"""
37
38
def sectionByID(self, sectionID):
39
"""
40
Get a library section by its ID.
41
42
Args:
43
sectionID (str): Section ID to retrieve
44
45
Returns:
46
LibrarySection: Matching section
47
"""
48
49
def all(self, **kwargs):
50
"""
51
Get all media items from all sections.
52
53
Args:
54
**kwargs: Filter parameters
55
56
Returns:
57
List[MediaObject]: All media items across sections
58
"""
59
60
def onDeck(self):
61
"""
62
Get items currently on deck (in progress or recommended).
63
64
Returns:
65
List[MediaObject]: On deck items
66
"""
67
68
def recentlyAdded(self):
69
"""
70
Get recently added media items.
71
72
Returns:
73
List[MediaObject]: Recently added items
74
"""
75
76
def search(self, title=None, libtype=None, **kwargs):
77
"""
78
Search across all library sections.
79
80
Args:
81
title (str, optional): Title to search for
82
libtype (str, optional): Media type filter ('movie', 'show', 'episode', 'artist', 'album', 'track')
83
**kwargs: Additional search parameters (studio, year, genre, etc.)
84
85
Returns:
86
List[MediaObject]: Search results
87
"""
88
89
def cleanBundles(self):
90
"""
91
Clean up old metadata bundles to reduce server storage usage.
92
Removes poster images and metadata packages for items no longer in library.
93
"""
94
95
def optimize(self):
96
"""
97
Optimize the library database to clean up unused or fragmented data.
98
Useful after adding or removing entire libraries or many items.
99
"""
100
```
101
102
### LibrarySection - Base Section Operations
103
104
Base class for all library sections providing common operations for media management and search functionality.
105
106
```python { .api }
107
class LibrarySection:
108
def __init__(self, server, data, initpath):
109
"""
110
Initialize library section.
111
112
Args:
113
server (PlexServer): Parent server instance
114
data: Section metadata
115
initpath (str): API initialization path
116
"""
117
118
@property
119
def title(self):
120
"""Section title/name."""
121
122
@property
123
def type(self):
124
"""Section type ('movie', 'show', 'artist', 'photo')."""
125
126
@property
127
def key(self):
128
"""Section API key."""
129
130
def all(self, **kwargs):
131
"""
132
Get all items in this section.
133
134
Args:
135
**kwargs: Filter parameters
136
137
Returns:
138
List[MediaObject]: All section items
139
"""
140
141
def get(self, title, **kwargs):
142
"""
143
Get a specific item by title.
144
145
Args:
146
title (str): Item title to find
147
**kwargs: Additional search parameters
148
149
Returns:
150
MediaObject: Matching item
151
152
Raises:
153
NotFound: If item not found
154
"""
155
156
def search(self, title=None, **kwargs):
157
"""
158
Search within this section.
159
160
Args:
161
title (str, optional): Title to search for
162
**kwargs: Search parameters (year, genre, director, etc.)
163
164
Returns:
165
List[MediaObject]: Search results
166
"""
167
168
def refresh(self):
169
"""Refresh/scan this library section for new content."""
170
171
def update(self, path=None):
172
"""
173
Update library section.
174
175
Args:
176
path (str, optional): Specific path to update
177
"""
178
179
def emptyTrash(self):
180
"""Empty the trash for this section."""
181
182
def analyze(self):
183
"""Analyze media in this section."""
184
185
def filters(self):
186
"""
187
Get available filter options for this section.
188
189
Returns:
190
List[FilterChoice]: Available filters
191
"""
192
193
def filterFields(self):
194
"""
195
Get available filter fields.
196
197
Returns:
198
List[str]: Filter field names
199
"""
200
```
201
202
### MovieSection - Movie Library Operations
203
204
Specialized library section for movie content with movie-specific operations and filtering.
205
206
```python { .api }
207
class MovieSection(LibrarySection):
208
TYPE = 'movie'
209
210
def unwatched(self):
211
"""
212
Get unwatched movies.
213
214
Returns:
215
List[Movie]: Unwatched movies
216
"""
217
218
def watched(self):
219
"""
220
Get watched movies.
221
222
Returns:
223
List[Movie]: Watched movies
224
"""
225
226
def decade(self, decade):
227
"""
228
Get movies from a specific decade.
229
230
Args:
231
decade (int): Decade (e.g., 1990, 2000, 2010)
232
233
Returns:
234
List[Movie]: Movies from decade
235
"""
236
237
def genre(self, genre):
238
"""
239
Get movies by genre.
240
241
Args:
242
genre (str): Genre name
243
244
Returns:
245
List[Movie]: Movies in genre
246
"""
247
248
def director(self, director):
249
"""
250
Get movies by director.
251
252
Args:
253
director (str): Director name
254
255
Returns:
256
List[Movie]: Movies by director
257
"""
258
```
259
260
### ShowSection - TV Show Library Operations
261
262
Specialized library section for TV show content with show and episode management capabilities.
263
264
```python { .api }
265
class ShowSection(LibrarySection):
266
TYPE = 'show'
267
268
def unwatched(self):
269
"""
270
Get shows with unwatched episodes.
271
272
Returns:
273
List[Show]: Shows with unwatched content
274
"""
275
276
def watched(self):
277
"""
278
Get completely watched shows.
279
280
Returns:
281
List[Show]: Fully watched shows
282
"""
283
284
def recentlyAdded(self, maxresults=50):
285
"""
286
Get recently added episodes.
287
288
Args:
289
maxresults (int): Maximum results to return
290
291
Returns:
292
List[Episode]: Recently added episodes
293
"""
294
295
def searchEpisodes(self, title=None, **kwargs):
296
"""
297
Search for episodes across all shows.
298
299
Args:
300
title (str, optional): Episode title to search for
301
**kwargs: Search parameters
302
303
Returns:
304
List[Episode]: Matching episodes
305
"""
306
```
307
308
### MusicSection - Music Library Operations
309
310
Specialized library section for music content with artist, album, and track management.
311
312
```python { .api }
313
class MusicSection(LibrarySection):
314
TYPE = 'artist'
315
316
def albums(self):
317
"""
318
Get all albums in this section.
319
320
Returns:
321
List[Album]: All albums
322
"""
323
324
def tracks(self):
325
"""
326
Get all tracks in this section.
327
328
Returns:
329
List[Track]: All tracks
330
"""
331
332
def genre(self, genre):
333
"""
334
Get artists by genre.
335
336
Args:
337
genre (str): Genre name
338
339
Returns:
340
List[Artist]: Artists in genre
341
"""
342
343
def decade(self, decade):
344
"""
345
Get music from a specific decade.
346
347
Args:
348
decade (int): Decade (e.g., 1980, 1990, 2000)
349
350
Returns:
351
List[Track]: Tracks from decade
352
"""
353
```
354
355
### PhotoSection - Photo Library Operations
356
357
Specialized library section for photo content with photoalbum and photo management.
358
359
```python { .api }
360
class PhotoSection(LibrarySection):
361
TYPE = 'photo'
362
363
def searchAlbums(self, title=None, **kwargs):
364
"""
365
Search for photo albums.
366
367
Args:
368
title (str, optional): Album title to search for
369
**kwargs: Search parameters
370
371
Returns:
372
List[Photoalbum]: Matching albums
373
"""
374
375
def searchPhotos(self, title=None, **kwargs):
376
"""
377
Search for individual photos.
378
379
Args:
380
title (str, optional): Photo title to search for
381
**kwargs: Search parameters
382
383
Returns:
384
List[Photo]: Matching photos
385
"""
386
```
387
388
### Hub - Content Recommendations
389
390
Represents content hubs providing recommendations and curated content collections.
391
392
```python { .api }
393
class Hub:
394
@property
395
def title(self):
396
"""Hub title."""
397
398
@property
399
def type(self):
400
"""Hub type."""
401
402
def items(self):
403
"""
404
Get items in this hub.
405
406
Returns:
407
List[MediaObject]: Hub items
408
"""
409
```
410
411
### Collections - Media Collections
412
413
Represents curated collections of related media items.
414
415
```python { .api }
416
class Collections:
417
@property
418
def title(self):
419
"""Collection title."""
420
421
def items(self):
422
"""
423
Get items in this collection.
424
425
Returns:
426
List[MediaObject]: Collection items
427
"""
428
```
429
430
## Search and Filtering Examples
431
432
### Basic Section Operations
433
434
```python
435
# Get all library sections
436
sections = plex.library.sections()
437
438
# Get specific section
439
movies = plex.library.section('Movies')
440
shows = plex.library.section('TV Shows')
441
music = plex.library.section('Music')
442
photos = plex.library.section('Photos')
443
444
# Get all items in a section
445
all_movies = movies.all()
446
recent_episodes = shows.recentlyAdded()
447
```
448
449
### Advanced Search Examples
450
451
```python
452
# Search by title
453
action_movies = movies.search(title='Action')
454
455
# Search by multiple criteria
456
recent_sci_fi = movies.search(genre='Science Fiction', year__gte=2020)
457
458
# Search by director
459
nolan_movies = movies.search(director='Christopher Nolan')
460
461
# Search unwatched content
462
unwatched_movies = movies.search(unwatched=True)
463
464
# Cross-library search
465
all_game_content = plex.library.search('Game of Thrones')
466
```
467
468
### Filter Operations
469
470
```python
471
# Get available filters for a section
472
filters = movies.filters()
473
474
# Use section-specific methods
475
recent_movies = movies.decade(2020)
476
comedy_movies = movies.genre('Comedy')
477
unwatched_shows = shows.unwatched()
478
```
479
480
### Library Maintenance
481
482
```python
483
# Refresh library sections
484
movies.refresh() # Scan for new movies
485
shows.update('/path/to/new/episodes') # Update specific path
486
487
# Clean up
488
movies.emptyTrash() # Empty deleted items
489
movies.analyze() # Analyze media files
490
```