0
# Media Objects and Metadata
1
2
Strongly-typed media objects for all content types including Movies, TV Shows, Episodes, Artists, Albums, Tracks, and Photos. Each object provides full metadata access, media-specific operations, and playback control with comprehensive attribute coverage matching the Plex API structure.
3
4
## Capabilities
5
6
### Base Media Classes
7
8
Core classes providing common functionality for all media types.
9
10
```python { .api }
11
class PlexObject:
12
"""Base class for all Plex API objects."""
13
14
def reload(self):
15
"""Reload object data from server."""
16
17
def fetchItem(self, ekey, cls=None):
18
"""
19
Fetch a single related item.
20
21
Args:
22
ekey (str): Element key to fetch
23
cls (class, optional): Expected class type
24
25
Returns:
26
PlexObject: Fetched item
27
"""
28
29
class PlexPartialObject(PlexObject):
30
"""Base for objects that can be partially loaded."""
31
32
def _reload(self):
33
"""Lazy load full object data."""
34
35
class Playable:
36
"""Mixin for playable media objects."""
37
38
def play(self, client=None):
39
"""
40
Play this media item.
41
42
Args:
43
client (PlexClient, optional): Client to play on
44
"""
45
46
def download(self, savepath=None, keep_original_name=False, **kwargs):
47
"""
48
Download media file.
49
50
Args:
51
savepath (str, optional): Download directory
52
keep_original_name (bool): Preserve original filename
53
**kwargs: Additional download parameters
54
55
Returns:
56
List[str]: Downloaded file paths
57
"""
58
59
def iterParts(self):
60
"""
61
Iterate over media parts.
62
63
Yields:
64
MediaPart: Media file parts
65
"""
66
67
def isWatched(self):
68
"""
69
Check if item is watched.
70
71
Returns:
72
bool: True if watched
73
"""
74
75
def markWatched(self):
76
"""Mark item as watched."""
77
78
def markUnwatched(self):
79
"""Mark item as unwatched."""
80
81
def rate(self, rating):
82
"""
83
Rate this item.
84
85
Args:
86
rating (float): Rating value (0.0-10.0)
87
"""
88
89
def updateProgress(self, time, state='stopped'):
90
"""
91
Update playback progress.
92
93
Args:
94
time (int): Current playback time in milliseconds
95
state (str): Playback state ('playing', 'paused', 'stopped')
96
"""
97
```
98
99
### Movie Objects
100
101
Movie media items with comprehensive metadata and movie-specific operations.
102
103
```python { .api }
104
class Movie(Playable, Video):
105
TYPE = 'movie'
106
107
@property
108
def title(self):
109
"""Movie title."""
110
111
@property
112
def year(self):
113
"""Release year."""
114
115
@property
116
def summary(self):
117
"""Movie plot summary."""
118
119
@property
120
def rating(self):
121
"""Movie rating."""
122
123
@property
124
def duration(self):
125
"""Movie duration in milliseconds."""
126
127
@property
128
def genres(self):
129
"""List of genre tags."""
130
131
@property
132
def directors(self):
133
"""List of director tags."""
134
135
@property
136
def writers(self):
137
"""List of writer tags."""
138
139
@property
140
def roles(self):
141
"""List of actor/role tags."""
142
143
@property
144
def countries(self):
145
"""List of country tags."""
146
147
@property
148
def collections(self):
149
"""List of collection tags."""
150
151
@property
152
def studio(self):
153
"""Production studio."""
154
155
@property
156
def contentRating(self):
157
"""Content rating (PG, R, etc.)."""
158
159
@property
160
def audienceRating(self):
161
"""Audience rating score."""
162
163
@property
164
def viewCount(self):
165
"""Number of times watched."""
166
167
@property
168
def addedAt(self):
169
"""Date added to library."""
170
171
@property
172
def updatedAt(self):
173
"""Date last updated."""
174
175
@property
176
def lastViewedAt(self):
177
"""Date last watched."""
178
179
def related(self):
180
"""
181
Get related movies.
182
183
Returns:
184
List[Movie]: Related movies
185
"""
186
```
187
188
### TV Show Objects
189
190
TV show hierarchy including Show, Season, and Episode objects with full navigation capabilities.
191
192
```python { .api }
193
class Show(Video):
194
TYPE = 'show'
195
196
@property
197
def title(self):
198
"""Show title."""
199
200
@property
201
def year(self):
202
"""Show start year."""
203
204
@property
205
def summary(self):
206
"""Show description."""
207
208
@property
209
def studio(self):
210
"""Production studio/network."""
211
212
@property
213
def contentRating(self):
214
"""Content rating."""
215
216
@property
217
def rating(self):
218
"""Show rating."""
219
220
@property
221
def genres(self):
222
"""List of genre tags."""
223
224
@property
225
def roles(self):
226
"""List of main cast members."""
227
228
@property
229
def leafCount(self):
230
"""Total number of episodes."""
231
232
@property
233
def viewedLeafCount(self):
234
"""Number of watched episodes."""
235
236
@property
237
def childCount(self):
238
"""Number of seasons."""
239
240
def episodes(self, **kwargs):
241
"""
242
Get all episodes in the show.
243
244
Args:
245
**kwargs: Filter parameters
246
247
Returns:
248
List[Episode]: Show episodes
249
"""
250
251
def episode(self, title=None, season=None, episode=None):
252
"""
253
Get a specific episode.
254
255
Args:
256
title (str, optional): Episode title
257
season (int, optional): Season number
258
episode (int, optional): Episode number
259
260
Returns:
261
Episode: Matching episode
262
"""
263
264
def seasons(self, **kwargs):
265
"""
266
Get all seasons in the show.
267
268
Args:
269
**kwargs: Filter parameters
270
271
Returns:
272
List[Season]: Show seasons
273
"""
274
275
def season(self, title=None, season=None):
276
"""
277
Get a specific season.
278
279
Args:
280
title (str, optional): Season title
281
season (int, optional): Season number
282
283
Returns:
284
Season: Matching season
285
"""
286
287
def watched(self):
288
"""
289
Get watched episodes.
290
291
Returns:
292
List[Episode]: Watched episodes
293
"""
294
295
def unwatched(self):
296
"""
297
Get unwatched episodes.
298
299
Returns:
300
List[Episode]: Unwatched episodes
301
"""
302
303
class Season(Video):
304
TYPE = 'season'
305
306
@property
307
def seasonNumber(self):
308
"""Season number."""
309
310
@property
311
def leafCount(self):
312
"""Number of episodes in season."""
313
314
@property
315
def viewedLeafCount(self):
316
"""Number of watched episodes."""
317
318
def episodes(self, **kwargs):
319
"""
320
Get episodes in this season.
321
322
Returns:
323
List[Episode]: Season episodes
324
"""
325
326
def episode(self, title=None, episode=None):
327
"""
328
Get specific episode in season.
329
330
Args:
331
title (str, optional): Episode title
332
episode (int, optional): Episode number
333
334
Returns:
335
Episode: Matching episode
336
"""
337
338
def show(self):
339
"""
340
Get parent show.
341
342
Returns:
343
Show: Parent show
344
"""
345
346
class Episode(Playable, Video):
347
TYPE = 'episode'
348
349
@property
350
def title(self):
351
"""Episode title."""
352
353
@property
354
def summary(self):
355
"""Episode description."""
356
357
@property
358
def seasonNumber(self):
359
"""Season number."""
360
361
@property
362
def episodeNumber(self):
363
"""Episode number within season."""
364
365
@property
366
def duration(self):
367
"""Episode duration in milliseconds."""
368
369
@property
370
def rating(self):
371
"""Episode rating."""
372
373
@property
374
def directors(self):
375
"""List of episode directors."""
376
377
@property
378
def writers(self):
379
"""List of episode writers."""
380
381
@property
382
def originallyAvailableAt(self):
383
"""Original air date."""
384
385
def season(self):
386
"""
387
Get parent season.
388
389
Returns:
390
Season: Parent season
391
"""
392
393
def show(self):
394
"""
395
Get parent show.
396
397
Returns:
398
Show: Parent show
399
"""
400
```
401
402
### Music Objects
403
404
Music hierarchy including Artist, Album, and Track objects with music-specific metadata and operations.
405
406
```python { .api }
407
class Artist(Audio):
408
TYPE = 'artist'
409
410
@property
411
def title(self):
412
"""Artist name."""
413
414
@property
415
def summary(self):
416
"""Artist biography."""
417
418
@property
419
def countries(self):
420
"""List of country tags."""
421
422
@property
423
def genres(self):
424
"""List of genre tags."""
425
426
@property
427
def similar(self):
428
"""List of similar artists."""
429
430
def albums(self, **kwargs):
431
"""
432
Get artist albums.
433
434
Returns:
435
List[Album]: Artist albums
436
"""
437
438
def album(self, title):
439
"""
440
Get specific album by title.
441
442
Args:
443
title (str): Album title
444
445
Returns:
446
Album: Matching album
447
"""
448
449
def tracks(self, **kwargs):
450
"""
451
Get all artist tracks.
452
453
Returns:
454
List[Track]: Artist tracks
455
"""
456
457
def track(self, title):
458
"""
459
Get specific track by title.
460
461
Args:
462
title (str): Track title
463
464
Returns:
465
Track: Matching track
466
"""
467
468
class Album(Audio):
469
TYPE = 'album'
470
471
@property
472
def title(self):
473
"""Album title."""
474
475
@property
476
def year(self):
477
"""Release year."""
478
479
@property
480
def summary(self):
481
"""Album description."""
482
483
@property
484
def genres(self):
485
"""List of genre tags."""
486
487
@property
488
def moods(self):
489
"""List of mood tags."""
490
491
@property
492
def leafCount(self):
493
"""Number of tracks."""
494
495
def tracks(self, **kwargs):
496
"""
497
Get album tracks.
498
499
Returns:
500
List[Track]: Album tracks
501
"""
502
503
def track(self, title):
504
"""
505
Get specific track by title.
506
507
Args:
508
title (str): Track title
509
510
Returns:
511
Track: Matching track
512
"""
513
514
def artist(self):
515
"""
516
Get album artist.
517
518
Returns:
519
Artist: Album artist
520
"""
521
522
class Track(Audio, Playable):
523
TYPE = 'track'
524
525
@property
526
def title(self):
527
"""Track title."""
528
529
@property
530
def duration(self):
531
"""Track duration in milliseconds."""
532
533
@property
534
def trackNumber(self):
535
"""Track number on album."""
536
537
@property
538
def discNumber(self):
539
"""Disc number for multi-disc albums."""
540
541
@property
542
def rating(self):
543
"""Track rating."""
544
545
@property
546
def viewCount(self):
547
"""Play count."""
548
549
@property
550
def lastViewedAt(self):
551
"""Last played date."""
552
553
def artist(self):
554
"""
555
Get track artist.
556
557
Returns:
558
Artist: Track artist
559
"""
560
561
def album(self):
562
"""
563
Get parent album.
564
565
Returns:
566
Album: Parent album
567
"""
568
```
569
570
### Photo Objects
571
572
Photo media types including photoalbums and individual photos.
573
574
```python { .api }
575
class Photoalbum(PlexPartialObject):
576
TYPE = 'photoalbum'
577
578
@property
579
def title(self):
580
"""Album title."""
581
582
@property
583
def summary(self):
584
"""Album description."""
585
586
@property
587
def leafCount(self):
588
"""Number of photos."""
589
590
def photos(self, **kwargs):
591
"""
592
Get photos in this album.
593
594
Returns:
595
List[Photo]: Album photos
596
"""
597
598
def photo(self, title):
599
"""
600
Get specific photo by title.
601
602
Args:
603
title (str): Photo title
604
605
Returns:
606
Photo: Matching photo
607
"""
608
609
class Photo(PlexPartialObject):
610
TYPE = 'photo'
611
612
@property
613
def title(self):
614
"""Photo title."""
615
616
@property
617
def summary(self):
618
"""Photo description."""
619
620
@property
621
def year(self):
622
"""Photo year."""
623
624
@property
625
def addedAt(self):
626
"""Date added to library."""
627
628
@property
629
def originallyAvailableAt(self):
630
"""Original photo date."""
631
632
def download(self, savepath=None, keep_original_name=False):
633
"""
634
Download photo file.
635
636
Args:
637
savepath (str, optional): Download directory
638
keep_original_name (bool): Preserve original filename
639
640
Returns:
641
str: Downloaded file path
642
"""
643
644
def photoalbum(self):
645
"""
646
Get parent photo album.
647
648
Returns:
649
Photoalbum: Parent album
650
"""
651
```
652
653
## Usage Examples
654
655
### Movie Operations
656
657
```python
658
# Get a movie and access metadata
659
movie = plex.library.section('Movies').get('Inception')
660
661
print(f"Title: {movie.title}")
662
print(f"Year: {movie.year}")
663
print(f"Rating: {movie.rating}")
664
print(f"Duration: {movie.duration // 60000} minutes")
665
print(f"Genres: {[g.tag for g in movie.genres]}")
666
print(f"Directors: {[d.tag for d in movie.directors]}")
667
668
# Mark as watched and rate
669
movie.markWatched()
670
movie.rate(9.0)
671
672
# Download movie
673
movie.download(savepath='/downloads/')
674
```
675
676
### TV Show Navigation
677
678
```python
679
# Navigate show hierarchy
680
show = plex.library.section('TV Shows').get('Game of Thrones')
681
seasons = show.seasons()
682
latest_season = seasons[-1]
683
episodes = latest_season.episodes()
684
685
# Mark entire show as watched
686
show.markWatched()
687
688
# Get specific episode
689
episode = show.episode(season=1, episode=1)
690
print(f"Episode: {episode.title}")
691
print(f"Air Date: {episode.originallyAvailableAt}")
692
```
693
694
### Music Library Operations
695
696
```python
697
# Browse music library
698
artist = plex.library.section('Music').get('The Beatles')
699
albums = artist.albums()
700
abbey_road = artist.album('Abbey Road')
701
tracks = abbey_road.tracks()
702
703
# Play a track
704
come_together = abbey_road.track('Come Together')
705
come_together.play()
706
707
# Access metadata
708
print(f"Track: {come_together.title}")
709
print(f"Duration: {come_together.duration // 1000} seconds")
710
print(f"Play Count: {come_together.viewCount}")
711
```
712
713
### Photo Management
714
715
```python
716
# Browse photos
717
photos_section = plex.library.section('Photos')
718
albums = photos_section.all()
719
vacation_album = photos_section.get('Vacation 2023')
720
721
# Get photos in album
722
photos = vacation_album.photos()
723
for photo in photos[:5]: # First 5 photos
724
print(f"Photo: {photo.title}")
725
print(f"Date: {photo.originallyAvailableAt}")
726
727
# Download photo
728
photo.download(savepath='/photo_downloads/')
729
```