0
# Media Library & Content
1
2
Comprehensive media library access including browsing sections, searching content, managing metadata, and working with movies, TV shows, music, and photos.
3
4
## Capabilities
5
6
### Library Access
7
8
Main interface for browsing and searching across all media libraries.
9
10
```python { .api }
11
class Library:
12
def sections(self):
13
"""
14
Get all library sections.
15
16
Returns:
17
list: List of LibrarySection objects (MovieSection, ShowSection, etc.)
18
"""
19
20
def section(self, name):
21
"""
22
Get library section by name.
23
24
Args:
25
name (str): Section name (e.g., 'Movies', 'TV Shows')
26
27
Returns:
28
LibrarySection: Specific section object
29
30
Raises:
31
NotFound: If section with specified name doesn't exist
32
"""
33
34
def search(self, title=None, libtype=None, **kwargs):
35
"""
36
Search across entire library.
37
38
Args:
39
title (str, optional): Title to search for
40
libtype (str, optional): Media type ('movie', 'show', 'artist', 'photo')
41
**kwargs: Additional search filters
42
43
Returns:
44
list: List of matching media objects
45
"""
46
47
def recentlyAdded(self):
48
"""
49
Get recently added media across all sections.
50
51
Returns:
52
list: List of recently added media objects
53
"""
54
55
def onDeck(self):
56
"""
57
Get on deck (in-progress) media.
58
59
Returns:
60
list: List of media objects that are in progress
61
"""
62
63
def sectionByID(self, sectionId):
64
"""
65
Get library section by ID.
66
67
Args:
68
sectionId (int): Section ID number
69
70
Returns:
71
LibrarySection: Specific section object
72
73
Raises:
74
NotFound: If section with specified ID doesn't exist
75
"""
76
77
def cleanBundles(self):
78
"""Clean unused metadata bundles to free disk space."""
79
80
def emptyTrash(self):
81
"""Empty the library trash for all sections."""
82
83
def optimize(self):
84
"""Optimize library database for better performance."""
85
```
86
87
### Library Sections
88
89
Base functionality for all library sections.
90
91
```python { .api }
92
class LibrarySection:
93
"""Base class for all media library sections."""
94
95
def get(self, title, year=None):
96
"""
97
Get specific item by title.
98
99
Args:
100
title (str): Item title to find
101
year (int, optional): Year for disambiguation
102
103
Returns:
104
Media object matching the title
105
106
Raises:
107
NotFound: If no item matches the criteria
108
"""
109
110
def all(self):
111
"""
112
Get all items in section.
113
114
Returns:
115
list: All media items in this section
116
"""
117
118
def search(self, title=None, **kwargs):
119
"""
120
Search within this section.
121
122
Args:
123
title (str, optional): Title to search for
124
**kwargs: Additional filters (year, genre, etc.)
125
126
Returns:
127
list: List of matching items
128
"""
129
130
def refresh(self):
131
"""Refresh section metadata from disk."""
132
133
def update(self):
134
"""Update section settings and configuration."""
135
136
def history(self, maxresults=None, mindate=None):
137
"""
138
Get playback history for this section.
139
140
Args:
141
maxresults (int, optional): Maximum number of results
142
mindate (datetime, optional): Earliest date to include
143
144
Returns:
145
list: List of historical playback records
146
"""
147
```
148
149
### Movie Library
150
151
Specialized functionality for movie collections.
152
153
```python { .api }
154
class MovieSection(LibrarySection):
155
"""Movie library section with movie-specific features."""
156
157
def recentlyAdded(self):
158
"""Get recently added movies."""
159
160
def recentlyViewed(self):
161
"""Get recently watched movies."""
162
163
def decade(self):
164
"""Get movies grouped by decade."""
165
166
def genre(self):
167
"""Get movies grouped by genre."""
168
169
def contentRating(self):
170
"""Get movies grouped by content rating."""
171
172
def unwatched(self):
173
"""Get unwatched movies."""
174
175
def watched(self):
176
"""Get watched movies."""
177
178
def collections(self):
179
"""
180
Get movie collections in this section.
181
182
Returns:
183
list: List of Collection objects
184
"""
185
```
186
187
### TV Show Library
188
189
Specialized functionality for TV show collections.
190
191
```python { .api }
192
class ShowSection(LibrarySection):
193
"""TV show library section with show-specific features."""
194
195
def seasons(self):
196
"""Get all seasons across all shows."""
197
198
def episodes(self):
199
"""Get all episodes across all shows."""
200
201
def recentlyAired(self):
202
"""Get recently aired episodes."""
203
204
def recentlyAdded(self):
205
"""Get recently added shows and episodes."""
206
```
207
208
### Music Library
209
210
Specialized functionality for music collections.
211
212
```python { .api }
213
class MusicSection(LibrarySection):
214
"""Music library section with music-specific features."""
215
216
def artists(self):
217
"""Get all artists."""
218
219
def albums(self):
220
"""Get all albums."""
221
222
def tracks(self):
223
"""Get all tracks."""
224
225
def playlists(self):
226
"""Get music playlists."""
227
228
def stations(self):
229
"""Get radio stations."""
230
```
231
232
### Photo Library
233
234
Specialized functionality for photo collections.
235
236
```python { .api }
237
class PhotoSection(LibrarySection):
238
"""Photo library section with photo-specific features."""
239
240
def photoalbums(self):
241
"""Get photo albums."""
242
243
def photos(self):
244
"""Get all photos."""
245
246
def years(self):
247
"""Get photos grouped by year."""
248
249
def tags(self):
250
"""Get photo tags."""
251
```
252
253
### Movie Objects
254
255
Rich movie objects with comprehensive metadata.
256
257
```python { .api }
258
class Movie:
259
"""Feature film with rich metadata."""
260
261
@property
262
def title(self): ...
263
@property
264
def year(self): ...
265
@property
266
def summary(self): ...
267
@property
268
def rating(self): ...
269
@property
270
def duration(self): ...
271
@property
272
def contentRating(self): ...
273
274
@property
275
def genres(self):
276
"""List of genre tags."""
277
278
@property
279
def directors(self):
280
"""List of director objects."""
281
282
@property
283
def writers(self):
284
"""List of writer objects."""
285
286
@property
287
def roles(self):
288
"""List of cast member objects."""
289
290
def play(self, client=None):
291
"""Play movie on specified client."""
292
293
def markPlayed(self):
294
"""Mark movie as watched."""
295
296
def markUnplayed(self):
297
"""Mark movie as unwatched."""
298
299
def uploadSubtitles(self, filepath):
300
"""
301
Upload subtitle file for this movie.
302
303
Args:
304
filepath (str): Path to subtitle file to upload
305
"""
306
307
def searchSubtitles(self, language='en'):
308
"""
309
Search for available subtitles.
310
311
Args:
312
language (str): Language code for subtitles
313
314
Returns:
315
list: List of available subtitle results
316
"""
317
318
def downloadSubtitles(self, subtitle, filepath=None):
319
"""
320
Download subtitle file.
321
322
Args:
323
subtitle: Subtitle object to download
324
filepath (str, optional): Path to save subtitle file
325
"""
326
327
def removeSubtitles(self, subtitle):
328
"""
329
Remove subtitle track.
330
331
Args:
332
subtitle: Subtitle track to remove
333
"""
334
335
def optimize(self, **kwargs):
336
"""
337
Optimize video file with transcoding.
338
339
Args:
340
**kwargs: Optimization parameters
341
"""
342
```
343
344
### TV Show Objects
345
346
Hierarchical TV show structure with shows, seasons, and episodes.
347
348
```python { .api }
349
class Show:
350
"""TV series container with seasons and episodes."""
351
352
@property
353
def title(self): ...
354
@property
355
def year(self): ...
356
@property
357
def summary(self): ...
358
359
def seasons(self):
360
"""Get all seasons for this show."""
361
362
def season(self, seasonNumber):
363
"""Get specific season by number."""
364
365
def episodes(self):
366
"""Get all episodes across all seasons."""
367
368
def episode(self, season=None, episode=None):
369
"""Get specific episode."""
370
371
def watched(self):
372
"""Get watched episodes."""
373
374
def unwatched(self):
375
"""Get unwatched episodes."""
376
377
class Season:
378
"""TV show season container."""
379
380
@property
381
def show(self):
382
"""Parent show object."""
383
384
@property
385
def seasonNumber(self): ...
386
387
def episodes(self):
388
"""Get all episodes in this season."""
389
390
def episode(self, episode):
391
"""Get specific episode by number."""
392
393
class Episode:
394
"""Individual TV episode."""
395
396
@property
397
def show(self):
398
"""Parent show object."""
399
400
@property
401
def season(self):
402
"""Parent season object."""
403
404
@property
405
def episodeNumber(self): ...
406
@property
407
def seasonNumber(self): ...
408
@property
409
def title(self): ...
410
@property
411
def summary(self): ...
412
```
413
414
### Music Objects
415
416
Hierarchical music structure with artists, albums, and tracks.
417
418
```python { .api }
419
class Artist:
420
"""Music artist or band."""
421
422
@property
423
def title(self): ...
424
@property
425
def summary(self): ...
426
427
def albums(self):
428
"""Get all albums by this artist."""
429
430
def album(self, title):
431
"""Get specific album by title."""
432
433
def tracks(self):
434
"""Get all tracks by this artist."""
435
436
def track(self, title):
437
"""Get specific track by title."""
438
439
class Album:
440
"""Music album with track listing."""
441
442
@property
443
def title(self): ...
444
@property
445
def year(self): ...
446
@property
447
def artist(self):
448
"""Album artist object."""
449
450
def tracks(self):
451
"""Get all tracks on this album."""
452
453
def track(self, title):
454
"""Get specific track by title."""
455
456
class Track:
457
"""Individual music track."""
458
459
@property
460
def title(self): ...
461
@property
462
def artist(self):
463
"""Track artist object."""
464
465
@property
466
def album(self):
467
"""Parent album object."""
468
469
@property
470
def trackNumber(self): ...
471
@property
472
def discNumber(self): ...
473
@property
474
def duration(self): ...
475
476
def sonicallySimilar(self, **kwargs):
477
"""
478
Find tracks sonically similar to this track.
479
480
Args:
481
**kwargs: Search parameters for similarity matching
482
483
Returns:
484
list: List of similar Track objects
485
"""
486
```
487
488
### Photo Objects
489
490
Photo albums and individual photos with EXIF data.
491
492
```python { .api }
493
class Photoalbum:
494
"""Photo album container."""
495
496
@property
497
def title(self): ...
498
499
def photos(self):
500
"""Get all photos in this album."""
501
502
def photo(self, title):
503
"""Get specific photo by title."""
504
505
class Photo:
506
"""Individual photo with EXIF metadata."""
507
508
@property
509
def title(self): ...
510
@property
511
def year(self): ...
512
@property
513
def originallyAvailableAt(self): ...
514
515
# EXIF properties
516
@property
517
def make(self): ... # Camera manufacturer
518
@property
519
def model(self): ... # Camera model
520
@property
521
def lens(self): ... # Lens information
522
@property
523
def iso(self): ... # ISO setting
524
@property
525
def aperture(self): ... # Aperture setting
526
@property
527
def exposure(self): ... # Exposure time
528
```
529
530
### Metadata Classes
531
532
Rich metadata support for organizing and filtering content.
533
534
```python { .api }
535
# Tag classes for organizing content
536
class Genre:
537
"""Genre classification tag."""
538
@property
539
def tag(self): ...
540
@property
541
def count(self): ...
542
543
class Director:
544
"""Director information."""
545
@property
546
def tag(self): ... # Director name
547
@property
548
def role(self): ... # Director role
549
550
class Role:
551
"""Cast member information."""
552
@property
553
def tag(self): ... # Actor name
554
@property
555
def role(self): ... # Character name
556
@property
557
def thumb(self): ... # Actor photo
558
559
class Collection:
560
"""Collection membership."""
561
@property
562
def tag(self): ... # Collection name
563
564
# Additional metadata classes
565
class Country:
566
"""Country of origin."""
567
568
class Studio:
569
"""Production studio."""
570
571
class Writer:
572
"""Writer/screenplay credits."""
573
```
574
575
## Usage Examples
576
577
### Library Browsing
578
579
```python
580
from plexapi.server import PlexServer
581
582
plex = PlexServer('http://localhost:32400', token='your-token')
583
584
# Get all library sections
585
sections = plex.library.sections()
586
for section in sections:
587
print(f"{section.title}: {section.type}")
588
589
# Access specific sections
590
movies = plex.library.section('Movies')
591
shows = plex.library.section('TV Shows')
592
music = plex.library.section('Music')
593
594
# Access section by ID (useful when section names change)
595
section_1 = plex.library.sectionByID(1) # First library section
596
```
597
598
### Movie Operations
599
600
```python
601
# Get specific movie
602
movie = movies.get('The Matrix', year=1999)
603
print(f"Duration: {movie.duration // 60000} minutes")
604
print(f"Rating: {movie.rating}")
605
606
# Browse movie metadata
607
for genre in movie.genres:
608
print(f"Genre: {genre.tag}")
609
610
for actor in movie.roles[:5]: # First 5 actors
611
print(f"{actor.tag} as {actor.role}")
612
613
# Search for movies
614
action_movies = movies.search(genre='Action')
615
recent_movies = movies.recentlyAdded()
616
```
617
618
### TV Show Operations
619
620
```python
621
# Get specific show
622
show = shows.get('The Office')
623
print(f"Seasons: {len(show.seasons())}")
624
625
# Get specific episode
626
episode = show.episode(season=2, episode=1)
627
print(f"S{episode.seasonNumber:02d}E{episode.episodeNumber:02d}: {episode.title}")
628
629
# Browse episodes
630
season_1 = show.season(1)
631
for ep in season_1.episodes():
632
status = "✓" if ep.isWatched else "○"
633
print(f"{status} {ep.title}")
634
```
635
636
### Music Operations
637
638
```python
639
# Browse music library
640
music = plex.library.section('Music')
641
artists = music.artists()
642
643
# Get specific artist
644
artist = music.get('The Beatles')
645
albums = artist.albums()
646
647
# Get specific album and tracks
648
album = artist.album('Abbey Road')
649
for track in album.tracks():
650
print(f"{track.trackNumber}. {track.title} ({track.duration // 1000}s)")
651
```
652
653
### Photo Operations
654
655
```python
656
# Browse photo library
657
photos = plex.library.section('Photos')
658
albums = photos.photoalbums()
659
660
# Get specific album
661
vacation = photos.get('Summer Vacation 2023')
662
for photo in vacation.photos():
663
print(f"{photo.title} - {photo.year}")
664
if photo.make:
665
print(f" Camera: {photo.make} {photo.model}")
666
```
667
668
### Search Operations
669
670
```python
671
# Search across all libraries
672
results = plex.search('star wars')
673
for item in results:
674
print(f"{item.title} ({item.type})")
675
676
# Library-wide search with filters
677
movies = plex.library.search(libtype='movie', year=2020)
678
shows = plex.library.search(libtype='show', genre='Comedy')
679
680
# Advanced section search
681
action_movies = movie_section.search(
682
genre='Action',
683
year__gte=2010, # Released 2010 or later
684
rating__gte=7.0 # Rating 7.0 or higher
685
)
686
```
687
688
### Library Maintenance
689
690
```python
691
# Clean up library
692
plex.library.cleanBundles() # Remove unused metadata bundles
693
plex.library.emptyTrash() # Empty all library trash
694
plex.library.optimize() # Optimize database
695
696
# Section-specific maintenance
697
movies = plex.library.section('Movies')
698
movies.refresh() # Refresh metadata from disk
699
movies.update() # Update section configuration
700
701
# View section history
702
history = movies.history(maxresults=50)
703
for entry in history:
704
print(f"{entry.user.title} watched {entry.title} on {entry.viewedAt}")
705
```
706
707
### Video Subtitle Management
708
709
```python
710
# Get a movie for subtitle operations
711
movie = plex.library.section('Movies').get('The Matrix')
712
713
# Search for available subtitles
714
subtitle_results = movie.searchSubtitles('en')
715
for result in subtitle_results:
716
print(f"Subtitle: {result.language} - {result.provider}")
717
718
# Upload custom subtitle file
719
movie.uploadSubtitles('/path/to/matrix_subtitles.srt')
720
721
# Download subtitle
722
if subtitle_results:
723
movie.downloadSubtitles(subtitle_results[0], '/path/to/download/')
724
725
# Remove subtitle track
726
existing_subtitles = movie.subtitleStreams()
727
if existing_subtitles:
728
movie.removeSubtitles(existing_subtitles[0])
729
730
# Optimize video file
731
movie.optimize(
732
deviceProfile='Universal TV',
733
videoQuality=8,
734
audioQuality=8
735
)
736
```
737
738
### Music Discovery
739
740
```python
741
# Find similar tracks
742
track = plex.library.section('Music').get('The Beatles').album('Abbey Road').track('Come Together')
743
744
# Get sonically similar tracks
745
similar_tracks = track.sonicallySimilar(limit=20)
746
for similar in similar_tracks:
747
print(f"Similar: {similar.artist().title} - {similar.title}")
748
749
# Create playlist from similar tracks
750
from plexapi.playlist import Playlist
751
similar_playlist = Playlist.create(
752
server=plex,
753
title=f'Similar to {track.title}',
754
items=similar_tracks[:10]
755
)
756
```
757
758
### Advanced Search Examples
759
760
```python
761
# Complex movie searches
762
# Movies from 2020+ with specific genres and ratings
763
modern_hits = movies.search(
764
year__gte=2020,
765
genre=['Action', 'Thriller'],
766
rating__gte=7.5,
767
contentRating__in=['PG-13', 'R']
768
)
769
770
# Unwatched movies by specific director
771
nolan_unwatched = movies.search(
772
director='Christopher Nolan',
773
unwatched=True
774
)
775
776
# TV show searches
777
# Shows with specific number of seasons
778
long_series = shows.search(
779
unwatched=False, # Shows you've watched
780
year__lte=2010, # Older shows
781
leafCount__gte=50 # At least 50 episodes
782
)
783
784
# Music searches with advanced filters
785
# High-rated albums from specific decade
786
classic_albums = music.search(
787
libtype='album',
788
year__gte=1970,
789
year__lte=1979,
790
rating__gte=4.0
791
)
792
793
# Recently added tracks by genre
794
new_rock = music.search(
795
libtype='track',
796
genre='Rock',
797
addedAt__gte=datetime.now() - timedelta(days=30)
798
)
799
```
800
801
### Cross-Library Discovery
802
803
```python
804
import datetime
805
from datetime import timedelta
806
807
# Find content added in last week across all libraries
808
recent_cutoff = datetime.datetime.now() - timedelta(days=7)
809
all_recent = plex.library.search(addedAt__gte=recent_cutoff)
810
811
print(f"Found {len(all_recent)} items added in last week:")
812
for item in all_recent[:10]: # Show first 10
813
section_name = item.section().title
814
print(f"- {item.title} ({item.type}) in {section_name}")
815
816
# Search for specific actor across all movie libraries
817
actor_name = "Tom Hanks"
818
actor_movies = plex.library.search(
819
libtype='movie',
820
actor=actor_name
821
)
822
823
print(f"\n{actor_name} appears in {len(actor_movies)} movies:")
824
for movie in actor_movies:
825
print(f"- {movie.title} ({movie.year})")
826
827
# Find all content with specific keyword in title
828
keyword_results = plex.library.search(title='star')
829
by_type = {}
830
for item in keyword_results:
831
item_type = item.type
832
if item_type not in by_type:
833
by_type[item_type] = []
834
by_type[item_type].append(item)
835
836
for media_type, items in by_type.items():
837
print(f"\n{media_type.title()}s with 'star' in title: {len(items)}")
838
for item in items[:5]: # Show first 5 of each type
839
print(f" - {item.title}")
840
```